Любой проект, который будет использоваться другими разработчиками, потребует потрясающей документации.

Самое главное для любой документации - это поддерживаться в хорошем состоянии.

Vue 3 и новый инструмент сборки Vite дают нам другой путь.

Представляем Vitepress.

В этом кратком руководстве мы увидим, как мы можем использовать Vitepress для быстрого создания документации для нашего приложения Vue.

Вот что у нас будет в конце нашего приложения.

В восторге?

Я тоже. Давай займемся этим.

Так что же такое Витепресс?

Vitepress - это генератор статических сайтов на базе Vue, построенный на основе Vite.

Названный младшим братом Vuepress в документации (который использует Vitepress), он имеет некоторые преимущества перед своим аналогом.

  • Построен на Vite, а не на Webpack, поэтому более быстрое время запуска, горячая перезагрузка и т. Д.
  • Использует Vue3 для уменьшения полезной нагрузки JS
  • Легче

Одна из причин, по которой Vitepress может достичь этих целей, заключается в том, что он гораздо более самоуверенный и конкретный, чем Vuepress, который с годами стал более сложным.

Хотя он не предназначен для полной замены Vuepress в качестве генератора статических сайтов Vue, Vitepress предлагает легкую альтернативу. Для большинства проектов, таких как документация и простые сайты, специфика и минимализм Vitepress упростят разработку.

Хорошо - давайте создадим наш проект Vitepress

Чтобы начать работу с Vitepress, первое, что мы хотим сделать, это создать наш каталог.

mkdir vite-hello-world
cd vite-hello-world

Затем мы хотим инициализировать наш менеджер пакетов и добавить Vitepress - для этого урока я буду использовать npm.

npm init
npm i --save-dev vitepress

Затем мы захотим добавить наши скрипты Vitepress в наш файл package.json.

"scripts": {
  "docs:dev": "vitepress dev docs",
  "docs:build": "vitepress build docs",
  "docs:serve": "vitepress serve docs"
},

Хорошо, давайте создадим папку docs и сделаем наш первый файл разметки.

mkdir docs
echo '# Hello World' > docs/index.md

Запустим наше приложение.

npm run docs:dev

Мы создали свой сайт! Если мы перейдем к http://localhost:3000, мы увидим, что наш файл разметки отображается на веб-странице!

Захватывающе! Давайте начнем настраивать наш сайт и использовать больше функций Vitepress.

Настройка нашего сайта Vitepress

Vitepress Навигация

Добавить несколько страниц на ваш сайт Vitepress так же просто, как создать больше файлов уценки.

Давайте создадим несколько страниц и подкаталогов в нашем проекте - теперь наш docs/ directory должен выглядеть так.

Когда Vitepress создает нашу SPA-навигацию, он использует путь к каждому файлу уценки для создания маршрута. Кроме того, файлы с именем index.md в любой папке также могут указываться с помощью /.

Например, наша файловая структура преобразуется в следующие маршруты:

## Routing!

[docs/index.md](/) -> /

[docs/contact.md](/contact) -> /contact

[about/index.md](/about/) -> /about/

[about/our-story.md](/about/our-story) -> /about/our-story

В наших файлах уценки у нас есть три способа связи с маршрутами. Мы можем использовать базовый URL, добавить .md или .html - все будет правильно ссылаться на нужный компонент.

### All these options work!

[docs/contact](/contact) | 
[docs/contact.md](/contact.md) |
[docs/contact.html](/contact.html)

Добавление панели навигации и боковой панели на наш сайт

Vitepress дает нам отличную тему по умолчанию. Это минималистичный, но мощный и простой в настройке.

Во-первых, давайте добавим на наш сайт навигацию с помощью боковой панели и панели навигации.

Для этого нам нужно создать файл конфигурации - мы можем сделать это в папке /docs/.vitepress/, в которой будут храниться наши файлы, специфичные для Vitepress. Наш файл будет называться ./vitepress/config.js, и ему просто нужно будет экспортировать объект JS.

module.exports = {
  title: 'Vitepress Tutorial', // appended to all page titles
}

Внутри этого объекта давайте добавим свойство с именем themeConfig, которое выглядит примерно так.

themeConfig: {
  nav: [

  ],
  sidebar: [

  ]
}

Чтобы добавить элементы на нашу навигационную панель, нам просто нужно добавить объекты в наш nav массив в формате { text: 'ANCHOR-TEXT', link: 'PATH' }, давайте добавим ссылку на нашу домашнюю страницу, страницу контактов и страницу с информацией.

nav: [
  { text: 'Home', link: '/' },
  { text: 'About', link: '/about/' },
  { text: 'Contact', link: '/contact' }
],

Точно так же можно добавить на нашу боковую панель. Давайте добавим ссылки на некоторые из наших заголовков.

sidebar: [
   { text: 'Our Story', link: '/about/our-story' }
]

Возвращаясь к нашему браузеру, теперь мы видим, что Vitepress создает довольно красивую панель навигации и боковую панель всего с помощью нескольких строк конфигурации.

С боковыми панелями Vitepress мы можем сделать одну замечательную вещь - это изменить боковую панель в зависимости от того, на какой странице мы работаем.

Допустим, мы хотим, чтобы на нашей домашней странице отображались заголовки, но мы хотим, чтобы на всех наших страницах отображалась только что созданная боковая панель.

Первое, что нам нужно сделать, это создать нашу our-story боковую панель в виде переменной.

const primarySidebar = [
  { text: 'Our Story', link: '/about/our-story' }
]

Вернувшись к нашему объекту themeConfig, мы хотим изменить нашу боковую панель на объект, где имя свойства - это путь, а значение - массив боковой панели.

sidebar: {
  '/about/': primarySidebar, // everything in the /about/ subdirectory
  '/contact': primarySidebar, // contact page
  
  // we don't need to do anything to index
  // because the default sidebar is created via page headings
}

Теперь, если мы проверим сайт - мы увидим, что наша домашняя страница имеет другую боковую панель, чем все остальные.

Фантастика.

Встроенные элементы в Vitepress

Vitepress поддерживает несколько элементов, которые вы можете просто объявить в своих проектах либо в config.js, либо прямо в Markdown.

Я расскажу только о некоторых из наиболее часто используемых мной. Щелкните здесь, чтобы просмотреть полный список элементов.

Блоки кода

При написании хорошей документации жизненно важны примеры кода. Vitepress позволяет быстро добавлять блоки кода, а также указывать, какой язык программирования он использует.

``` js
console.log('Hello World')
```

Оглавление

Добавление оглавления может быть еще одним отличным способом упростить навигацию по статическому сайту Vue.

/docs/index.md
[[toc]]

Таблицы стилей Github

К таблицам в Vitepress нужно немного привыкнуть, но простота и возможность изменять выравнивание столбцов делают его ценным.

| Headings      | Are           | Centered    |
| ------------- |:-------------:| -----:      |
| left align    | centered      | right align |
| zebra striped | rows          | easy        |

Конфигурация Markdown Frontmatter

Хотя мы можем использовать ваш ./vuepress/config.js для создания конфигураций всего сайта, иногда нам может потребоваться больший контроль над отдельными страницами.

К счастью, мы можем управлять каждой страницей, используя блок YAML в верхней части наших файлов уценки. Vitepress позволяет нам объявить этот блок, заключив его в три пунктирные линии (---)

Например, предположим, что мы хотим изменить заголовок и удалить боковую панель со страницы контактов.

---
title: Contact
---

# Contact

Зайдя в наш https://localhost:3000/contact - видим, что он работает.

Здесь мы можем настроить множество разных вещей. Ознакомьтесь с документацией по всем параметрам Frontmatter.

Развертывание вашего приложения Vitepress

Мы уже видели, что можем создать вашу локальную среду с помощью npm run docs:dev, но как насчет создания приложения для производственной среды?

Во-первых, нам нужно создать ваше приложение с помощью команды

npm run dev:build

Результат сборки по умолчанию будет /docs/.vuepress/dist. Папка dist для нашего примера выглядит так.

Затем мы можем развернуть эту dist папку на любой платформе, которую захотим.

Если мы хотим проверить, как выглядит наша сборка, мы можем запустить функцию serve Vitepress для создания локального статического веб-сервера.

npm run docs:serve

Заключение

Вот и все!

Vitepress - отличный способ обеспечить актуальность вашей документации. Благодаря своему продуманному дизайну, он предоставляет вам быстрый и простой способ поддерживать ваши статические сайты.

Я хотел бы узнать, что вы думаете о Витепресс!

Если вы хотите узнать больше о Vue 3, скачайте мою бесплатную шпаргалку по Vue 3 с такими важными знаниями, как Composition API, синтаксис шаблона Vue 3 и обработка событий.