Введение в VuePress: основные операции и темы

Возможно, вы уже слышали о VuePress: почти сразу же после своего появления он стал продуктом дня на ProductHunt.

Что особенного в VuePress? И что вообще такое VuePress? По сути, это генератор статических сайтов на базе Vue.js, предназначенный, в частности, для создания веб-сайтов, на которых публикуется документация.

Почему это так важно? Создатель VuePress и Vue.js, Эван Ю, умеет создавать невероятно простое и гибкое программное обеспечение. После выполнения пары команд VuePress у вас будет предварительно обработанный, оптимизированный для SEO одностраничный сайт с полной поддержкой Vue.js. Несколько строк конфигурации – и он персонализирован согласно вашим потребностям.

1: Начало работы с VuePress

Установка VuePress

$ npm install -g vuepress

Добавление данных

Создайте файл README.md и напишите в нем какой-нибудь markdown (который можно совмещать с выражениями Vue.js).

## Hello VuePress!
_How are you doing?_
> **I'm doing fine, thanks!**
_Great, I was wondering what `49 + 32` is?_
> **{{49 + 32}}**
_Could you repeat that a few times?_
> **Sigh...**
<p v-for="i of 3">{{49 + 32}}</p>

Запустите в этой папке:

$ vuepress dev

и перейдите по полученному URL-адресу. VuePress поддерживает горячую перезагрузку модуля.

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

Сборка

Когда сайт будет готов к публикации, запустите команду:

$ vuepress build

Результат будет помещен в .vuepress/dist, аккуратно собран и минифицирован с помощью Webpack.

Но пока что мы не будем публиковать наш тестовый сайт. Давайте сначала внесем еще несколько изменений.

2: Публикация метаданных

Для начала создайте в каталоге вашего проекта еще пару файлов markdown. Назовем их Page-1.md и Page-2.md. В Page-1.md поместите следующее:

# This is Page 1
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.

В Page-2.md вставьте эти строки:

# This is Page 2
Lorem ipsum dolor sit amet, consectetur adipisicing 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.

Если сейчас вы проверите браузер, то заметите, что на загруженной ранее странице волшебным образом появились ссылки на следующую и предыдущую публикацию. Текст этих ссылок будет совпадать с первыми заголовками этих записей. В данном случае это будет This is Page 1/2. Это не совсем удобно.

Добавьте блок YAML блок в начало каждого из наших двух файлов.

Page-1.md

---
title: Page 1
# We can even add meta tags to the page! This sets the keywords meta tag.
# <meta name="keywords" content="my SEO keywords"/>
meta:
- name: keywords
- content: my SEO keywords
---
# This is Page 1
...

Page-2.md

---
title: Page 2
---
# This is Page 2
...

После этого в ссылках будет текст Page 1 и Page 2, а не This is Page…

Полный список основных метаданных можно найти здесь.

3: Добавление боковой панели

Навигация по ссылкам неудобна. Кроме того, страницы кажутся неупорядоченными. Боковая панель могла бы решить обе эти проблемы.

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

Создайте в каталоге вашего проекта файл .vuepress/config.js и с его помощью включите боковую панель. Вставьте в файл:

module.exports = {
themeConfig: {
sidebar: [
'/',
'/Page 1',
'/Page 2'
] }
}

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

4: Включение панели навигации

Итак, у нас есть страницы и боковая панель, но сайт все равно кажется немного сырым. Давайте включим навигационную панель и функцию поиска. Вставьте в файл vuepress/config.js следующее:

module.exports = {
title: 'My VuePress Site',
themeConfig: {
sidebar: [
...
],
}
}

Как видите, все, что вам нужно сделать для создания панели навигации и поля поиска, – это просто добавить заголовок на свой сайт! Кстати, функция поиска работает прямо «из коробки».

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

5: Использование компонентов Vue

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

Примечание: Компоненты Vue должны поддерживать SSR, поэтому вам не следует делать ничего, что изменяет DOM или взаимодействует с API-интерфейсами только для браузера, за пределами хука mount() или прослушивателей событий.

Создайте компонент Vue, который позволяет увеличивать и уменьшать число счетчика. Что действительно важно, VuePress автоматически обнаруживает компоненты Vue в .vuepress/components. Сейчас мы создадим .vuepress/components/NumberModifier.vue.

<template>
<div class="number-modifier">
<button @click="increment()">+</button>
<strong> {{value}} </strong>
<button @click="decrement()">-</button>
</div>
</template>
<script>
export default {
props: ['start'],
// We have to copy the value because we can't use v-model with
// nothing to bind to.
// (VuePress doesn't have support for reactive page variables at the moment.)
data() {
return {
value: this.start
}
},
methods: {
increment() { this.value++ },
decrement() { this.value-- }
}
}
</script>

Вот так мы можем использовать этот компонент в любой записи. Например, на странице Page-1.md:

...
# This is Page 1
**Our Component:**
<NumberModifier :start="5"></NumberModifier>
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.

Такой же метод применяется к любому компоненту. Это отличный способ отобразить компоненты, которые вы пишете, вместе с их документацией. А еще это позволяет создавать более продвинутые сайты.

6: Пользовательские темы

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

Стандартная тема использует Stylus в качестве препроцессора CSS. Если все, что вам нужно сделать, это изменить один-два цвета, вы можете сделать это, просто добавив файл .vuepress/override.styl и изменив в нем несколько значений. При необходимости вы даже можете поместить туда несколько переопределений CSS.

Тема по умолчанию достаточно проста, поэтому чаще всего в ней меняют цвет акцента.

.vuepress/override.styl

// Color configuration
$accentColor = #3eaf7c
$textColor = #2c3e50
$borderColor = #eaecef
$codeBgColor = #282c34
// Layout configuration
$navbarHeight = 3.6rem
$sidebarWidth = 20rem
$contentWidth = 740px

Создание новой темы

В контексте VuePress темы – это просто коллекции компонентов Vue и связанных с ними ресурсов. Если вы хотите создать сайт со своей собственной темой, самый простой способ – это извлечь тему по умолчанию с помощью команды:

$ vuepress eject

Все, что она делает, – копирует файлы стандартной темы в .vuepress/theme.

Обратите внимание на тему по умолчанию и вы заметите, что она невероятно проста. Менее 25 файлов, в среднем около 70 строк в каждом, и почти нет шаблонов.

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

Заключение

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

Читайте также: Создание документации с помощью Vue и VuePress

Tags: ,

Добавить комментарий