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

VuePress использует однофайловые компоненты Vue для пользовательских тем. Чтобы использовать пользовательский шаблон, создайте каталог .vuepress/theme в корневом каталоге документации, а затем создайте файл Layout.vue:

.
└─ .vuepress
   └─ theme
      └─ Layout.vue

С этого момента всё аналогично разработке обычного приложения Vue. Это зависит от вас, каким образом организовывать свою тему.

# Мета-данные сайта и страницы

Компонент Layout будет вызываться один раз для каждого файла .md в каталоге docs, и мета-данные для всего сайта и этой конкретной страницы будут внедряться соответственно как свойства this.$site и this.$page, которые внедряются и в каждый компонент приложения.

Это значение $site этого самого веб-сайта:

{
  "title": "VuePress",
  "description": "Генератор статических сайтов на Vue",
  "base": "/",
  "pages": [
    {
      "lastUpdated": 1524027677000,
      "path": "/",
      "title": "VuePress",
      "frontmatter": {}
    },
    ...
  ]
}

Значения title, description и base копируются из соответствующих полей файла .vuepress/config.js. pages содержит массив объектов мета-данных для каждой страницы, включая её путь, заголовок (явно указанный в YAML front matter или взятый из первого заголовка на странице), и любые другие данные в формате YAML front matter в этом файле.

Так выглядит объект $page для страницы, на которую вы сейчас смотрите:

{
  "lastUpdated": 1524847549000,
  "path": "/guide/custom-themes.html",
  "title": "Пользовательские темы",
  "headers": [/* ... */],
  "frontmatter": {}
}

Если была указана опция themeConfig в .vuepress/config.js, она будет также доступна через $site.themeConfig. Вы можете использовать её чтобы позволить пользователю настраивать поведение вашей темы — например, уточнять категории или порядок страниц. Вы можете использовать их вместе с $site.pages для создания динамических ссылок навигации.

И наконец, не забывайте про свойства this.$route и this.$router, которые также доступны, как часть API Vue Router приложения.

# Выдержки контента

Если файл markdown содержит комментарий <!-- more -->, любое содержимое выше комментария будет извлечено и доступ к нему будет возможен через $page.excerpt. Если вы создаёте пользовательскую тему для ведения блога, эти данные можно использовать для отображения списка записей блога с выдержками текста.

# Подстановка содержимого страницы

Скомпилированное содержимое текущего .md файла будет доступно через специальный компонент <Content/>, зарегистрированный глобально. Вам необходимо использовать его где-либо в вашем шаблоне, чтобы отобразить содержимое страницы. Для простой темы, это может быть один компонент Layout.vue со следующим содержимым:

<template>
  <div class="theme-container">
    <Content/>
  </div>
</template>

# Доработки уровня приложения

Поскольку приложение VuePress по сути обычное приложение Vue, то вы можете применять доработки на уровне приложения создав файл .vuepress/enhanceApp.js, который будет импортирован в приложение, если присутствует. Файл должен экспортировать по умолчанию (export default) функцию-хук, которая получит объект, содержащий некоторые значения уровня приложения. Вы можете использовать этот хук для установки дополнительных плагинов Vue, регистрации глобальных компонентов, или добавления хуков маршрутизатора:

export default ({
  Vue,      // версия Vue, используемая в приложении VuePress
  options,  // настройки корневого экземпляра Vue
  router,   // экземпляр маршрутизатора приложения
  siteData  // мета-данные сайта
}) => {
  // ...применяем доработки к приложению
}

# Использование темы в качестве зависимости

Темы могут быть опубликованы на npm в сыром формате однофайловых компонентов Vue под именем vuepress-theme-xxx.

Для использования темы из зависимости, укажите опцию theme в .vuepress/config.js:

module.exports = {
  theme: 'awesome'
}

VuePress попробует найти и использовать node_modules/vuepress-theme-awesome/Layout.vue.

# Изменение темы по умолчанию

Вы можете скопировать исходный код стандартной темы в .vuepress/theme чтобы полностью настроить тему под ваши нужды, с помощью команды vuepress eject [targetDir]. Обратите внимание, однако, что как только вы сделаете извлечение конфигурации, то вы станете сами по себе и не будете получать будущие обновления или исправления ошибок для стандартной темы, даже если обновите VuePress.