От нуля до деплоя: разработка системы документации с помощью Vue и VuePress
Перевод статьи William Imoh: Zero to Deploy: Build A Documentation System with Vue and VuePress. Опубликовано с разрешения автора.
Документация для разработчика — это его хлеб насущный и очень часто случается так, что бывает трудно построить систему документации к разрабатываемым проектам.
В этой статье будет создана статическая документации, которая одновременно является одностраничным приложением (SPA), в основе которого находится фреймворк Vue и генератор статических сайтов VuePress.
Примечание переводчика: на данный момент доступен неофициальный перевод документации VuePress, выполненный сообществом Translation Gang, которое также занимается переводом Vue-продуктов, включая VuePress. До тех пор пока VuePress находится в стадии разработки, официальные переводы не принимаются, но сообщество уже перевело документацию VuePress и после выхода стабильной версии этот перевод будет доступен на официальном сайте.
Что такое статические сайты
В общих словах можно сказать, что статические сайты — это страницы, которые хранятся в том же виде, в котором будут показаны пользователю. У таких сайтов нет обычного прямого взаимодействия типа клиент-сервер, за исключением возможного варианта с подключенными сторонними приложениями.
В интернете существует большое количество генераторов статических сайтов, которые различаются между собой отдельными характеристиками. У одних генераторов преимуществом является скорость работы и время загрузки; у других — гибкость настройки; третьи — обладают большим набором функциональности.
Статические сайты предпочтительны в случаях, когда важна скорость работы веб-страницы и низкая вероятность утечки секретной информации из-за отсутствия сервера.
Особенностью недавно выпущенного VuePress как генератора статических сайтов является предустановленная тема оформления, которую можно использовать для создания документации тогда, когда для создания пользовательской темы нет времени. В этой статье будет использоваться тема по умолчанию.
Почему именно VuePress?
Я хочу сказать — почему бы и не VuePress! По умолчанию VuePress генерирует из структурированных по папкам markdown-файлов HTML-файлы, которые будут использоваться в дальнейшем для показа пользователям.
Генератор VuePress из коробки имеет в своем составе фреймворк Vue, библиотеку VueRouter для создания маршрутизации и систему webpack для сборки проекта. Во время сборки все markdown-файлы преобразуются в Vue-шаблоны, в то время как все дополнительные файлы обрабатываются системой сборки webpack.
Преобразование markdown-файлов в Vue-шаблоны предоставляет нам возможность использовать нативные Vue-скрипты в том виде, в каком они используются в обычных Vue-компонентах.
VuePress является системой, хорошо оптимизированной для SEO и предоставляющей инструменты Google Analytics для анализа посещаемости страниц. Также VuePress имеет встроенную поддержку системы поиска по сайту при помощи индексации заголовков страниц и отображения их в процессе поиска.
VuePress имеет встроенную поддержку адаптивной разметки страниц, а также позволяет видоизменять или создавать свою собственную разметку. В рамках данной статьи мы создадим простую систему документации с поддержкой темы оформления по умолчанию; также мы воспользуемся такой возможностью, как Vue in Markdown, что позволит нам встроить простой счетчик внутри markdown-файла.
Окончательный вид проекта будет следующим:
Необходимые условия
Для успешного освоения данного руководства необходимы хорошие знания HTML, CSS и JavaScript. Знания Vue.js не являются необходимыми, но будут существенным преимуществом.
Установка
Для создания проекта нам понадобятся установленные Node.js и менеджер пакетов npm. Проверить их наличие и узнать их версии можно, набрав в терминале команду:
node -v && npm -vСледующим шагом будет развертывание нового проекта. Для этого создадим директорию scotch-vuepress и перейдем в неё:
mkdir scotch-vuepress && cd $_Затем выполним инициализацию проекта при помощи npm:
npm init -yЭта команда выполнит предварительную настройку проекта — создаст файл package.json.
Теперь нужно локально установить VuePress:
npm install -D vuepressПримечание переводчика: На момент перевода данной статьи использовалась актуальная версия — VuePress
0.10.1Автором перевода эта версия была опробована применительно к статье и приведена в примерах ниже. С исходным кодом примера, использующего данную версию, можно ознакомится по ссылке VuePress Test. На момент написания статьи её автором William Imoh версия VuePress была0.5.0.
После установки VuePress нам будет доступна тема оформления документации, которая встроена в VuePress изначально; этой темой мы воспользуемся при построении нашего проекта. Однако нам потребуется внести изменения в саму структуру проекта — создать необходимые папки и файлы, для начала с произвольным содержимым.
Создание папок и файлов
При создании папок в VuePress нужно принимать во внимание, что расположение файлов и директорий в структуре проекта имеет существенное значение. Каждый markdown-файл в любой из директорий компилируется в HTML-файл и маршрутом до этого файла будет являться родительская директория.
Для начала давайте создадим папку docs, внутри которой будут размещаться все будущие папки и конфигурационные файлы нашего проекта:
mkdir docs && cd $_В этой корневой директории нам нужно создать специальную папку .vuepress и две дополнительные папки проекта: counter и guide.
Обратите внимание, чтобы все маршруты проекта работали, необходимо в каждой из папок создать по одному файлу README.md. Это служит домашним маршрутом для каждого конкретного подраздела.
Внутри директории counter расположены дополнительные markdown-файлы, которые будут сгенерированы в обычные HTML-файлы. Помимо этих файлов внутри папки counter расположен файл README.mdдля генерации маршрута до этой директории. Аналогичная структура файлов присутствует и в папке guide.
Директория .vuepress предназначена для служебных целей — внутри неё будет располагаться директория с компонентами; папка dist, которая будет сгенерирована автоматически в процессе сборки проекта; файл config.js, в котором будут храниться настройки проекта.
Создание компонентов
Для учебных целей данного проекта нам потребуется создать очень простой счетчик при помощи Vue.js. Для этого в директории .vuepress создадим поддиректорию components, в которую поместим два файла — counter.vue и my-header.vue. Первый компонент будет являться счетчиком, а второй — простым заголовком.
Содержимое компонента my-header.vue следующее:
<template>
<div>
<h1>This Header is actually a Vue Template</h1>
</div>
</template><script></script><style scoped></style>
Содержимое компонента counter.vue:
<template>
<div class="counter">
<h1 class="counter__title">{{ number }}</h1>
<button class="counter__button" type="button" @click="increment()">increment</button>
<button class="counter__button" type="button" @click="decrement()">decrement</button>
</div>
</template><script>
export default {
data() {
return{
number: 0,
}
},
methods:{
increment() {
if (this.number >= 0) {
this.number += 1
}
},
decrement() {
if (this.number > 0) {
this.number -= 1
}
}
}
}
</script><style scoped>.counter {
display: inline-block;
margin-left: 30%;
}.counter__title {
text-align: center;
}.counter__button {
display: inline-block;
padding: 20px;
margin: 10px;
font-weight: 700;
border-radius: 5px;
box-shadow: 0px 0px 5px 0px rgb(11, 11, 114);
text-transform: capitalize;
}</style>
Оба компонента готовы для использования в проекте и мы может двигаться дальше.
Создание markdown-файлов
Продолжим создание проекта путем добавления markdown-файлов в папки counter и guide. По нижеследующим ссылкам можно увидеть, что из себя представляет содержимое обеих директорий и сами markdown-файлы — папка counter и папка guide.
Frontmatter используется для динамического создания заголовка каждой индивидуальной страницы. Обратите внимание, что компонент counter добавлен в содержимое файла counter-app.md.
Эти markdown-файлы при последующей сборке проекта будут преобразованы в статические страницы. Для создания маршрутов в проекте к этим директориям в каждой из папок расположен файл README.md. Frontmatter внутри markdown-файлов служит для создания динамических свойств страницы.
Добавим файл README.md для корневой директории docs:
---
home: true
actionText: See Counter App
actionLink: /counter/counter-app
features:
- title: Embedded Vue Counter
details: A Vue counter developed using Vue is embedded in this doc, now that's the power of VuePress!
- title: Fun Docs made with VuePress
details: This entire doc was basically made with VuePress which parsed markdown files and corresponding assets using webpack.
footer: Developed using VuePress by William Imoh
---Исходя из логики нашего проекта, компонент my-header должен находится по корневому маршруту, поэтому нам нужно немного переделать файл README.md — добавить в него компонент my-header:
---
home: true
actionText: See Counter App
actionLink: /counter/counter-app
features:
- title: Embedded Vue Counter
details: A Vue counter developed using Vue is embedded in this doc, now that's the power of VuePress!
- title: Fun Docs made with VuePress
details: This entire doc was basically made with VuePress which parsed markdown files and corresponding assets using webpack.
footer: Developed using VuePress by William Imoh
---
<my-header></my-header>Таким образом, у нас есть все необходимые файлы для проекта. Можно двигаться дальше и приступить к настройке навигации и боковой панели сайта, используя файл конфигурации .vuepress/config.js.
Настройка разметки
Файл config.js используется для настройки системы документации. В создаваемом нами проекте содержимое этого файла будет иметь вид объекта со следующими свойствами:
module.exports = {
title: 'Scotch VuePress',
description: "A demo documentation using VuePress",
themeConfig:{
nav: [
{ text: 'COUNTER', link: '/counter/' },
{ text: 'GUIDE', link: '/guide/' },
],
sidebar: [
{
title: 'Counter',
collapsable: false,
children: [
'/counter/counter-app'
]
},
{
title: 'API Guide',
collapsable: false,
children: [
'/guide/guide',
'/guide/api'
]
}
]
}
}Поле title устанавливает заголовок проекта; в поле description задается описание проекта, что необходимо для SEO. Этот заголовок и описание автоматически предоставляют индексированную поисковую систему на веб-сайте с помощью строки поиска.
Следующим свойством объекта является themeConfig, который в свою очередь является объектом и обладает свойствами для конфигурации темы оформления. Например, чтобы создать панель навигации на сайте, в объекте themeConfig мы добавляем свойство nav. Это свойство в свою очередь является массивом объектов, в которых устанавливается заголовок и маршрут для каждого из элементов навигации. Более подробно с вопросом настройки темы оформления можно ознакомиться здесь — Default Theme Config.
В настройках файла config.js мы использовали сгруппированные боковые панели для того, чтобы в любой момент времени иметь быстрый доступ ко всей документации. Панель навигации можно сделать сворачиваемой при помощи свойства collapsable в каждой из групп боковой панели. Больше информации о настройке боковой панели можно найти здесь — Sidebar.
На данный момент у нас выполнены все настройки проекта, поэтому можно запустить сборку при помощи команды:
vuepress dev docsПримечание переводчика: приведенная выше команда подразумевает, что пакет vuepress установлен глобально в системе, при помощи команды
npm install --global vuepress. Если же пакетvuepressустановлен только локально, то команда запуска должна выглядеть так —npx vuepress dev docs.
Локальный сервер запускается на порту 8080. Хорошей новостью для нас является тот факт, что VuePress из коробки обладает возможностью горячей перезагрузки, которая выполняется каждый раз при внесении любых изменений в разрабатываемом проекте.
Обратите внимание на то, что перезагрузка сервера все же необходима в том случае, когда выполняется создание новых Vue-компонентов в момент работы запущенного сервера.
Обратите внимание на заголовок, созданный при помощи Vue-компонента.
На момент, когда запущен dev-сервер, основной целью является развёртывание проекта. Для того, чтобы немного привести всё в порядок, давайте отредактируем файл package.json и включим в него команду для запуска dev-сервера аналогично команде для сборки проекта.
Готовый вид файла package.json будет следующим:
{
"name": "scotch-vuepress",
"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": "MIT",
"devDependencies": {
"vuepress": "^0.5.0"
}
}Для того чтобы запустить процесс сборки статических страниц проекта, нужно выполнить команду:
npm run docs:buildПроцесс генерации статических страниц может занять некоторое время, после которого готовые страницы будут располагаться по пути .vuepress/dist.
Изменение стилей
VuePress имеет хорошую встроенную поддержку как статических файлов, так и webpack-файлов; благодаря этому VuePress осуществляет проверку правильности URL-адресов, прописанных в markdown-файлах, прежде чем будет выполнена сборка проекта.
Такая особенность VuePress позволяет нам внести некоторые изменения в цветовую палитру базовой темы оформления проекта. Выполнять переопределение цветов темы мы будем при помощи CSS-препроцессора Stylus.
Для этого в директории docs/.vuepress создадим файл override.styl. Именование переменных, для которых определены значения цветов, оставим так, как это сделано в официальной документации. В файле override.styl мы изменим значение переменной accentColor:
$accentColor = #cfa809
$textColor = #2c3e50
$borderColor = #eaecef
$codeBgColor = #282c34Чтобы изменения вступили в силу, необходимо перезапустить сервер командой:
npm run docs:devОбратите внимание, что изменения внутри файла
override.stylнемедленно отображаются в браузере.
Теперь мы полностью завершили создание системы документации нашего проекта:
Размещение на Netlify
Заключительной частью процесса создания нашего проекта будет его размещение в интернет на бесплатном хостинге Netlify.
Сервис Netlify предоставляет отличную возможность непрерывной интеграции с GitHub, GitLab или Bitbucket для размещения готовых проектов на этом хостинге.
Нижеследующие шаги позволят разместить наш проект на хостинге Netlify:
- Шаг 1 — необходимо создать учётные записи на GitHub и Netlify. Используя систему Git, разместить готовый проект на GitHub.
- Шаг 2 — под зарегистрированной учётной записью зайти на сервис Netlify и выбрать опцию “New site from Git”. Выберите систему GitHub и в ней — репозиторий с проектом.
- Шаг 3 — в репозитории выбираем ветку для размещения — master или же любую другую ветку, которую вы хотите разместить. В поле для задания команды сборки вводим строку
npm run docs:build. В поле директории сборки указываемdocs/.vuepress/dist. Нажимаем кнопку Deploy Site. Через некоторое время сайт будет размещен на сервере и у нас появится URL-ссылка для глобального доступа в интернет.
По указанной ниже ссылке располагается размещенный на Netlify проект, который был создан автором данной статьи — Scotch VuePress.
Заключение
Преимуществом статических сайтов является скорость их работы, безопасность и легкость поддержки. В данном руководстве при помощи VuePress мы создали сайт статических файлов (документацию), который одновременно является одностраничным приложением (SPA).
Система VuePress предоставляет гибкость при написании Vue-скриптов внутри markdown-файлов, что поднимает процесс создания статических файлов на новый уровень. В процессе создания документации можно легко изменять стандартную структуру проекта и соответствующих markdown-файлов.
В процессе чтения данного руководства можно воспользоваться ссылкой на репозиторий автора с готовым проектом, где вы можете оставлять свои комментарии и отклики.
Примечание переводчика: пример с более актуальной версией VuePress расположен здесь.
Приятного кодинга!
Слушайте наш подкаст в iTunes и SoundCloud, читайте нас на Medium, контрибьютьте на GitHub, общайтесь в группе Telegram, следите в Twitter и канале Telegram, рекомендуйте в VK и Facebook.
