Введение в VuePress и как его использовать

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

VuePress упрощает создание веб-сайтов с документацией без написания большого количества кода.

Что такое VuePress?

VuePress - это генератор статических сайтов на базе Vue, который генерирует HTML-страницы из файлов разметки. Это позволяет вам сосредоточиться на написании документации вместо того, чтобы работать над совершенствованием своего веб-сайта.

В VuePress каждая страница имеет свой собственный предварительно обработанный статический HTML-код, поэтому он обеспечивает отличную производительность загрузки, а также действительно удобен для SEO (поисковой оптимизации).

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

Установка VuePress и создание проекта

Установить VuePress и создать проект или добавить VuePress в существующий проект очень просто. Вы можете установить VuePress с помощью NPM:

npm install -g vuepress

или пряжей:

yarn global add vuepress

Вы также можете добавить VuePress в существующий проект. Для этой цели я рекомендую yarn, потому что, если в проекте есть зависимость Webpack 3.x, Npm не сможет сгенерировать правильное дерево зависимостей.

Для добавления VuePress в существующий проект используйте:

yarn add -D vuepress

Запуск проекта

Чтобы запустить проект, откройте командную строку, перейдите в рабочий каталог и введите vuepress dev, чтобы запустить сервер разработки.

Сначала мы получим ошибку 404 о том, что здесь ничего нет. Это потому, что мы еще не создали ни одного файла уценки, поэтому давайте просто воспользуемся командной строкой для создания нашего первого файла уценки:

echo '# Hello VuePress' > README.md

После этого вы увидите, что страница обновляется, показывая вам панель поиска, а также текст, который мы указали в команде echo. VuePress автоматически позволяет пользователям искать все теги h2 и h3, содержащиеся на веб-сайте.

Вы можете увидеть изображение страницы ниже:

Добавление файла конфигурации

Без какой-либо конфигурации страница не предлагает много функций, и у пользователя нет возможности перемещаться по сайту. Чтобы добавить пользовательские конфигурации, нам нужно создать файл config.js, который нам нужно поместить в папку .vuepress, которая будет содержать все файлы, относящиеся к VuePress.

Итак, наша новая структура проекта будет выглядеть так:

|-- Project
   |-- README.md
   |-- .vuepress
      |-- config.js

Теперь мы создадим объект Javascript, который мы можем использовать для определения наших конфигураций. В нем мы укажем заголовок и описание:

module.exports = {

 title: 'Hello VuePress',

 description: 'Just playing around'
}

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

Тема по умолчанию

Как упоминалось в начале статьи, VuePress поставляется с темой по умолчанию для таких вещей, как домашняя страница, навигационная панель, боковая панель и многие другие.

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

Вы можете получить тему по умолчанию из документации VuePress.

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

Итак, теперь наш корневой файл README.md выглядит примерно так:

---
home: true
heroImage: https://vuepress.vuejs.org/hero.png
actionText: Get Started →
actionLink: /guide/
features:
- title: Simplicity First
 details: Minimal setup with markdown-centered project structure helps you focus on writing.
- title: Vue-Powered
 details: Enjoy the dev experience of Vue + webpack, use Vue components in markdown, and develop custom themes with Vue.
- title: Performant
 details: VuePress generates pre-rendered static HTML for each page, and runs as an SPA once a page is loaded.
footer: MIT Licensed | Copyright © 2018-present Evan You
---
'# Hello VuePress'

Вы можете увидеть новый дизайн домашней страницы на изображении ниже:

Создание панели навигации

VuePress позволяет добавить панель навигации, указав объект themeConfig внутри файла config.js и передав ему массив объектов навигации.

Как и в официальной документации, мы добавим ссылку на страницу руководства, которая еще не создана, а также ссылку на google.com.

module.exports = {
   title: 'Hello VuePress',
   description: 'Just playing around',
   themeConfig: {
       nav: [
         { text: 'Home', link: '/' },
         { text: 'Guide', link: '/guide/' },
         { text: 'External', link: 'https://google.com' },
       ]
   }
}

Создание маршрутов

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

VuePress реализует простую в использовании систему маршрутизации. Для маршрута / guide / он ищет файл README.md внутри каталога руководств.

После того, как мы создали каталог и файл, наша структура проекта выглядит так:

|-- Project
   |-- README.md
   |-- .vuepress
      |-- config.js
   |-- guide
      |-- README.md

В качестве содержимого файла README.md мы просто введем несколько заголовков и текст lorem ipsum.

# Guide
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
## This is awesome
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Теперь, если мы перейдем на страницу руководства, мы увидим:

Создание боковой панели

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

Самый простой способ создать такую ​​боковую панель - указать sidebar: ‘auto’ внутри нашего themeConfig.

Код:

module.exports = {
   title: 'Hello VuePress',
   description: 'Just playing around',
   themeConfig: {
       nav: [
         { text: 'Home', link: '/' },
         { text: 'Guide', link: '/guide/' },
         { text: 'External', link: 'https://google.com' },
       ],
       sidebar: 'auto'
   }
}

Это создает боковую панель:

Это замечательно для нашего случая использования, но не работает, если у вас есть дополнительные файлы разметки. В этом случае вам необходимо указать объект боковой панели, содержащий массивы для каждой «главной» страницы.

В этом примере я создам еще один файл уценки под названием «More Informations.md», который также находится в каталоге руководства.

Файл просто содержит текст:

# More Informations
More Informations about our awesome project

Если вы снова посмотрите на боковую панель, вы увидите, что ничего не изменилось. Таким образом, автоматическая настройка не работает для дополнительных файлов разметки. Для этого нам нужно изменить код боковой панели следующим образом:

module.exports = {
   title: 'Hello VuePress',
   description: 'Just playing around',
   themeConfig: {
       nav: [
         { text: 'Home', link: '/' },
         { text: 'Guide', link: '/guide/' },
         { text: 'External', link: 'https://google.com' },
       ],
       sidebar: {
           '/guide/': [
               '',
               'More Informations'
           ]
       }
   }
}

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

Заключение

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

В этом посте я смог охватить лишь очень минимальное количество функций. Если вам интересно узнать больше о VuePress и его функциях, ознакомьтесь с официальной документацией и оставьте комментарий ниже, если вам нужна еще одна статья о VuePress.

Если вам понравилась эта статья, подпишитесь на мой Youtube канал и подпишитесь на меня в социальных сетях.

Код, описанный в этой статье, доступен как репозиторий Github.

Если у вас есть какие-либо вопросы или критические замечания, со мной можно связаться через Twitter или в разделе комментариев.