Создание документации с помощью Vue и VuePress
Development, Java | Комментировать запись
Документация – очень важная часть успешного проекта. Однако полноценная система документации требуется далеко не каждому проекту. Небольшому приложению или несложному инструменту, скорее всего, будет достаточно статической страницы.
VuePress обрабатывает файлы Markdown, структурированные по папкам, и собирает из них файлы HTML, которые можно обслуживать. VuePress поставляется вместе с Vue, Vue Router и webpack. Каждый файл Markdown анализируется как шаблон Vue, а объединяются ресурсы с помощью webpack. Обработка файлов Markdown в качестве шаблонов Vue позволяет также использовать родные сценарии Vue в виде однофайловых компонентов.
Примечание: Это руководство было написано с учетом ручной установки. Для автоматического создания скаффолда доступен инструмент под названием create-vuepress-site.
В этом мануале мы покажем, как с помощью построителя статических сайтов VuePress создать веб-сайт документации, который по сути является одностраничным приложением.
Требования
Если вы хотите следовать этой статье, вам понадобится локальная среда разработки Node.js. Чтобы создать такую среду, следуйте соответствующим инструкциям:
- Установка Node.js и настройка локальной среды разработки в macOS
- Установка Node.js в Debian 10
- Установка Node.js в CentOS 8
- Установка Node.js в Ubuntu 20.04
Это руководство было протестировано на Node 15.8.0, npm 7.5.4 и VuePress 1.8.2.
1: Создание проекта
В этом разделе мы создадим проект и установим VuePress.
Сначала создайте новый каталог для проекта:
mkdir vuepress-example
Перейдите в этот каталог:
cd vuepress-example
Инициализируйте новый проект:
npm init --yes
Эта команда быстро создаст скаффолд нового проекта и файл package.json.
Затем нам нужно локально установить VuePress как зависимость разработки:
npm install vuepress@1.8.2 --save-dev
После установки VuePress у вас будет все необходимое, потому что VuePress поставляется со стандартной темой документации (ее мы и будем использовать в этом руководстве).
На этом этапе нужно отредактировать стандартный package.json и внести в него сценарии для создания и обслуживания сайта VuePress.
Откройте package.json в редакторе кода и добавьте выделенные строки:
{
"name": "vuepress-example",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1",
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
},
"keywords": [],
"author": "",
"license": "ISC",
"devDependencies": {
"vuepress": "^1.8.2"
}
}
Мы установили VuePress и отредактировали package.json, чтобы иметь возможность использовать команды dev и build .
2: Создание домашней страницы
В этом разделе мы создадим структуру каталогов и файлы Markdown с текстом-заполнителем.
Будьте осторожны при создании папок в VuePress: он оценивает папки и файлы Markdown в соответствии со структурой их каталогов. Каждый файл Markdown в папке компилируется в HTML-документ, где маршрут является родительской папкой.
Сначала создайте каталог docs, он нужен для хранения компонентов и конфигурации:
mkdir docs
Теперь с помощью редактора кода создайте в этом каталоге новый файл index.md:
docs/index.md
---
home: true
actionText: Counter Component
actionLink: /counter/
features:
- title: Embedded Vue Compments
details: A Vue counter developed using Vue is embedded in this documentation. Now that's the power of VuePress!
- title: Documentation made with VuePress
details: This entire documentation was made with VuePress which parsed Markdown files and corresponding assets using webpack.
footer: Developed using VuePress by William Imoh
---
Специальный синтаксис «front matter» (в формате YAML, JSON и TOML) в файлах Markdown указывает VuePress на предоставление title, lang и других атрибутов.
На этом этапе вы можете собрать приложение и посмотреть, что у вас есть на данный момент:
npm run docs:dev
После сборки приложения вы получите сообщение о том, что команда выполнена успешно, и в нем же вы найдете URL-адрес (по умолчанию это должен быть localhost:8080).
Откройте этот URL в своем браузере. Код Markdown сгенерирует кнопку «See Counter App», информацию о функциях приложения и футер.
VuePress поставляется с функцией горячей перезагрузки, которая подтягивает любые изменения, внесенные в приложение во время разработки.
Перезагрузка сервера разработки требуется, если во время создания компонентов Vue локальный сервер разработки запущен.
3: Создание страницы Counter
Для примера в этом руководстве документация будет отслеживать детали компонента Counter, который увеличивает или уменьшает числовое значение.
В каталоге docs создайте новый подкаталог .vuepress:
mkdir docs/.vuepress
Здесь создайте новый подкаталог components:
mkdir docs/.vuepress/components
С помощью редактора кода создайте в каталоге .vuepress/components новый файл counter.vue и поместите в него:
<template>
<div class="counter">
<h1>{{ number }}</h1>
<button @click="increment">Increment</button>
<button @click="decrement">Decrement</button>
</div>
</template>
<script>
export default {
data() {
return {
number: 0
};
},
methods: {
increment() {
if (this.number >= 0) {
this.number++;
}
},
decrement() {
if (this.number > 0) {
this.number--;
}
}
}
};
</script>
<style scoped>
.counter {
display: inline-block;
margin-left: 30%;
}
button {
display: inline-block;
padding: 20px;
margin: 10px;
font-weight: bold;
border-radius: 5px;
box-shadow: 0px 0px 5px 0px rgb(11, 11, 114);
}
h1 {
text-align: center;
}
</style>
Этот код будет вести подсчет и отображать значение (number). Значение будет меняться в зависимости от количества взаимодействий с кнопками Increment и Decrement.
Давайте теперь создадим страницу для отображения компонента <counter/>.
В каталоге docs создайте новый подкаталог counter:
mkdir counter
Здесь нужно создать файл README.md. это можно сделать с помощью редактора кода:
---
title: Counter Component
---
# Counter Component
<counter/>
## Details
The `counter` component allows users to **Increment** and **Decrement** numeric values. The value starts at `0` and has a minimum value of `0`.
### Props
n/a
### State
n/a
Создайте в этом каталоге пару дополнительных страниц. В нашем примере это будет файл usage.md:
---
title: Counter Component - Usage
---
# Usage
Currently, this component is used in our app as part of a demonstration.
А также файл see-also.md:
---
title: Counter Component - See Also
---
# See Also
* [Number](https://en.wikipedia.org/wiki/Number)
* [Increment and decrement operators](https://en.wikipedia.org/wiki/Increment_and_decrement_operators)
Позже эти файлы будут преобразованы в статические страницы.
Теперь у нас есть все необходимые файлы Markdown.
4: Настройка макета и стилей
В этом разделе мы настроим сайт для отображения указанного заголовка, описания, навигации и боковой панели.
Для настройки системы документации используется файл config.js. С помощью редактора кода создайте в каталоге .vuepress новый файл counter.vue:
module.exports = {
title: 'VuePress',
description: 'A demo documentation using VuePress',
themeConfig: {
nav: [
{ text: 'Counter', link: '/counter/' }
],
sidebar: [
{
title: 'Counter',
collapsable: false,
children: [
['/counter/usage', 'Usage'],
['/counter/see-also', 'See Also']
]
}
]
}
};
Сначала мы указываем title – заголовок веб-сайта – и присваиваем ему description – описание, полезное для SEO. Это название и описание автоматически обеспечивают на веб-сайте индексируемую поисковую систему с панелью для поиска.
Следующим в сценарии идет объект themeConfig, который получает параметры, необходимые для реализации определенных функций в теме нашей страницы. Чтобы создать панель navbar, мы создаем массив nav, в котором содержатся объекты, определяющие отображаемый текст и маршрут каждого элемента. Узнать больше о navbar можно в официальной документации.
Этот код также содержит элемент sidebar, благодаря которому пользователи в любое время смогут быстро просмотреть меню в документации. Меню sidebar может сворачиваться по умолчанию – это настраивается с помощью свойства collapsable в группе sidebar. Вы можете узнать больше о sidebar в официальной документации.
В качестве последнего шага в настройке демонстрационного сайта мы с помощью styles заменим цвета по умолчанию.
В структуре каталогов docs/.vuepress/ создайте новый подкаталог по имени styles:
mkdir docs/.vuepress/styles
Теперь с помощью редактора кода создайте в каталоге .vuepress/styles новый файл по имени palette.styl с таким содержимым:
$accentColor = #cfa809
$textColor = #2c3e50
$borderColor = #eaecef
$codeBgColor = #282c34
Сохраните изменения и перезапустите сервер разработки с помощью команды:
npm run docs:dev
Обратите внимание: изменения, внесенные в файл styl, сразу же отразятся на странице в браузере.
Система документации готова!
Заключение
В этом руководстве мы с помощью VuePress разработали простой статический сайт для документации приложения.
VuePress обеспечивает гибкость написания сценариев Vue внутри файлов Markdown, что позволяет использовать интерактивные демонстрации. Статические сайты популярны благодаря своей скорости, безопасности и удобству обслуживания.
VuePress оптимизирован для SEO и по умолчанию предоставляет средства для внедрения на страницы сайта анализа с помощью Google Analytics. Кроме того, VuePress поставляется с простейшей поисковой системой, которая индексирует все заголовки на веб-сайте и отображает их при поиске. А еще VuePress предоставляет стандартный адаптивный макет для документации, но он также поддерживает пользовательские стилизованные макеты.
Если вы хотите продолжить обучение, попробуйте самостоятельно изменить этот тестовый проект: добавьте в него несколько новых папок и создайте соответствующие файлы Markdown.
Читайте также: Введение в Vuex: управление состоянием Vue.js
Tags: Vue.js, VuePress