VuePress

Настройки стандартной темы

ПРИМЕЧАНИЕ

Все опции, перечисленные на этой странице, применяются только к стандартной теме. Если вы используете пользовательскую тему, список настроек может отличаться.

Главная страница

Стандартная тема предоставляет шаблон главной страницы (который используется на главной странице этого сайта). Чтобы использовать её, укажите home: true и необходимую информацию в корневом README.mdYAML front matter. Она и будет использоваться на сайте:

---
home: true
heroImage: /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
---

Любой дополнительный контент после YAML front matter будет обрабатываться как обычный markdown и отображаться после секции возможностей.

Если вы хотите использовать совершенно иной шаблон главной страницы, вы также можете использовать другой пользовательский шаблон.

Панель навигации

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

Ссылки в панели навигации

Вы можете добавлять ссылки в панель навигации через themeConfig.nav:

// .vuepress/config.js
module.exports = {
  themeConfig: {
    nav: [
      { text: 'Главная', link: '/' },
      { text: 'Руководство', link: '/guide/' },
      { text: 'Ссылка на другой сайт', link: 'https://google.com' },
    ]
  }
}

Ссылки также могут быть выпадающими меню, если вы укажете массив items вместо link:

module.exports = {
  themeConfig: {
    nav: [
      {
        text: 'Languages',
        items: [
          { text: 'Chinese', link: '/language/chinese' },
          { text: 'Japanese', link: '/language/japanese' }
        ]
      }
    ]
  }
}

Кроме того, можно создавать группы в выпадающем меню, указывая вложенные элементы:

module.exports = {
  themeConfig: {
    nav: [
      {
        text: 'Languages',
        items: [
          { text: 'Группа 1', items: [/*  */] },
          { text: 'Группа 2', items: [/*  */] }
        ]
      }
    ]
  }
}

Отключение панели навигации

Для глобального отключения панели навигации используйте опцию themeConfig.navbar:

// .vuepress/config.js
module.exports = {
  themeConfig: {
    navbar: false
  }
}

Вы можете отключить панель навигации для определённых страниц через YAML front matter:

---
navbar: false
---

Боковая панель

Для добавления боковой панели используйте themeConfig.sidebar. Базовая конфигурация ожидает массив ссылок:

// .vuepress/config.js
module.exports = {
  themeConfig: {
    sidebar: [
      '/',
      '/page-a',
      ['/page-b', 'Явно заданный текст ссылки']
    ]
  }
}

Вы можете опускать расширение .md, и пути заканчивающиеся на / будут указывать на */README.md. Текст для ссылки автоматически подставляется (либо из первого заголовка на странице, либо в явно указанном свойстве title в секции YAML front matter). Если вы хотите явно указать текст ссылки, используйте массив в формате [ссылка, текст].

Вложенность ссылок заголовков

Боковая панель автоматически отображает ссылки для заголовков текущей активной страницы, вложенные под ссылкой самой страницы. Вы можете настроить это поведение с помощью themeConfig.sidebarDepth. По умолчанию глубина 1, которая извлекает заголовки h2. Установка её в значение 0 отключает ссылки заголовков, а максимальное значение 2 будет извлекать заголовки h2 и h3.

Страница также может переопределять это значение в секции YAML front matter:

---
sidebarDepth: 2
---

Активность ссылок заголовков

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

module.exports = {
  themeConfig: {
    activeHeaderLinks: false, // По умолчанию: true
  }
}

ПРИМЕЧАНИЕ

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

Группировка в боковой панели

Вы можете разделить ссылки в боковой панели на несколько групп с помощью объектов:

// .vuepress/config.js
module.exports = {
  themeConfig: {
    sidebar: [
      {
        title: 'Группа 1',
        collapsable: false,
        children: [
          '/'
        ]
      },
      {
        title: 'Группа 2',
        children: [ /* ... */ ]
      }
    ]
  }
}

Группы в боковой панели по умолчанию свёрнуты. Вы можете заставить группу всегда показываться в развёрнутом виде с помощью опции collapsable: false.

Несколько боковых панелей

Если вы хотите отображать несколько боковых панелей для различных секций контента, сначала организуйте ваши страницы по каталогам для каждой желаемой секции:

.
├─ README.md
├─ contact.md
├─ about.md
├─ foo/
│  ├─ README.md
│  ├─ one.md
│  └─ two.md
└─ bar/
   ├─ README.md
   ├─ three.md
   └─ four.md

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

// .vuepress/config.js
module.exports = {
  themeConfig: {
    sidebar: {
      '/foo/': [
        '',     /* /foo/ */
        'one',  /* /foo/one.html */
        'two'   /* /foo/two.html */
      ],

      '/bar/': [
        '',      /* /bar/ */
        'three', /* /bar/three.html */
        'four'   /* /bar/four.html */
      ],

      // fallback
      '/': [
        '',        /* / */
        'contact', /* /contact.html */
        'about'    /* /about.html */
      ]
    }
  }
}

ВНИМАНИЕ

Убедитесь что указали fallback в конце конфигурации.

VuePress проверяет конфигурацию каждой боковой панели сверху вниз. Если fallback конфигурация будет первой, VuePress будет некорректно сопоставлять /foo/ или /bar/four.html, потому что в обоих случаях они начинаются с /.

Автоматическая боковая панель для простых страниц

Если вы хотите автоматически генерировать боковую панель, которая содержит только ссылки заголовков текущей страницы, вы можете использовать YAML front matter на этой странице:

---
sidebar: auto
---

Вы также можете включить её для всех страниц в файле конфигурации:

// .vuepress/config.js
module.exports = {
  themeConfig: {
    sidebar: 'auto'
  }
}

При наличии интернационализации, вы также можете указать опцию для конкретной локализации:

// .vuepress/config.js
module.exports = {
  themeConfig: {
     '/': {
       sidebar: 'auto'
     }
  }
}

Отключение боковой панели

Вы можете отключить боковую панель на некоторых страницах, указав в YAML front matter:

---
sidebar: false
---

Поле поиска

Встроенный поиск

Вы можете отключить встроенное поле поиска с помощью themeConfig.search: false, и указать сколько предположений нужно отображать через themeConfig.searchMaxSuggestions:

module.exports = {
  themeConfig: {
    search: false,
    searchMaxSuggestions: 10
  }
}

СОВЕТ

Встроенный поиск создаёт индекс только из заголовка страницы и тегов h2 и h3, если вам требуется полнотекстовый поиск, вы можете использовать поиск Algolia.

Поиск Algolia

Опция themeConfig.algolia позволяет вам использовать Algolia DocSearch вместо простого встроенного поиска. Чтобы использовать его, вам нужно указать apiKey и indexName:

module.exports = {
  themeConfig: {
    algolia: {
      apiKey: '<API_KEY>',
      indexName: '<INDEX_NAME>'
    }
  }
}

Подробнее в документации Algolia DocSearch.

Последнее обновление

Опция themeConfig.lastUpdated позволяет вам получить UNIX timestamp(ms) последнего git коммита каждого файла, и будет показывать внизу каждой страницы в указанном формате:

module.exports = {
  themeConfig: {
    lastUpdated: 'Последнее обновление', // string | boolean
  }
}

Обратите внимание, что опция по умолчанию в значении off. При указании строки string, она будет отображаться как префикс (значение по умолчанию: Last Updated).

ВНИМАНИЕ

Так как lastUpdated основывается на git, то использовать её можно только в git репозитории.

Ссылки на предыдущую / следующую страницы

Ссылки на предыдущую / следующую страницы автоматически определяются на основании порядка активной страницы в боковой панели. Вы можете также явно переопределить или отключить их с помощью секции YAML front matter:

---
prev: ./some-other-page
next: false
---

Git репозиторий и ссылки на редактирование страниц

Указание опции themeConfig.repo будет автоматически генерировать ссылку на GitHub в панели навигации и ссылки на редактирование текущей страницы внизу каждой страницы.

// .vuepress/config.js
module.exports = {
  themeConfig: {
    // Укажите GitHub. Это также может быть полный URL GitLab.
    repo: 'vuejs/vuepress',
    // Определяем текст заголовка
    // По умолчанию "GitHub"/"GitLab"/"Bitbucket", основываясь на `themeConfig.repo`
    repoLabel: 'Contribute!',

    // Опциональные настройки для генерации ссылок "Edit this page"

    // если ваша документация в другом репозитории от основного проекта:
    docsRepo: 'vuejs/vuepress',
    // если ваша документация не в корне вашего репозитория:
    docsDir: 'docs',
    // если ваша документация в отдельной ветке репозитория (по умолчанию 'master'):
    docsBranch: 'master',
    // по умолчанию false, измените на true для включения ссылок
    editLinks: true,
    // собственный текст для ссылки редактирования. По умолчанию "Edit this page"
    editLinkText: 'Помогите нам улучшить эту страницу!'
  }
}

Вы можете скрыть ссылки редактирования для отдельных страниц через YAML front matter:

---
editLink: false
---

Простое переопределение CSS

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

Вот несколько переменных основных цветов, которые вы можете изменить:

// показываем значения по умолчанию
$accentColor = #3eaf7c
$textColor = #2c3e50
$borderColor = #eaecef
$codeBgColor = #282c34

Пользовательский класс страниц

Иногда может потребоваться добавить уникальный класс для определённой страницы, чтобы, потом стилизовать содержимое только этой страницы в собственном CSS. Вы можете добавить класс в div контейнер темы с помощью pageClass в секции YAML front matter:

---
pageClass: custom-page-class
---

Теперь вы можете писать CSS только для этой страницы:

/* .vuepress/override.styl */

.theme-container.custom-page-class {
  /* правила для конкретной страницы сайта */
}

Пользовательский шаблон для отдельных страниц

По умолчанию, каждый файл *.md отображается в контейнере <div class="page">, наряду с боковой панелью, автоматически сгенерированными ссылками редактирования и ссылками на предыдущую/следующую страницу. Если вы хотите использовать полностью настраиваемый компонент вместо страницы (не затрагивая только панель навигации), вы можете указать компонент, который будет использоваться в секции YAML front matter:

---
layout: SpecialLayout
---

Тогда для этой страницы будет использован шаблон .vuepress/components/SpecialLayout.vue.

Извлечение конфигурации

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

Изменить эту страницу на GitHub
Последнее обновление: 2018-6-9 00:31:59