默认主题配置(default theme config)

提示

此页面上列出的所有选项仅适用于默认主题。如果你使用的是自定义主题,则选项可能会有所不同。

主页(Homepage)

默认主题提供了一个主页布局(用于该网站的主页)。要使用它,需要在你的根目录 README.mdYAML front matter 中指定 home:true 加上一些其他元数据。这是本网站使用的实际数据:

---
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,并在特性部分之后渲染。

If you want to use a completely custom homepage layout, you can also use a Custom Layout.

你可以通过 themeConfig.nav 将链接添加到导航栏中:

// .vuepress/config.js
module.exports = {
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Guide', link: '/guide/' },
      { text: 'External', link: 'https://google.com' },
    ]
  }
}

These links can also be dropdown menus if you provide an array of items instead of a link:

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

In addition, you can have sub groups inside a dropdown by having nested items:

module.exports = {
  themeConfig: {
    nav: [
      {
        text: 'Languages',
        items: [
          { text: 'Group1', items: [/*  */] },
          { text: 'Group2', items: [/*  */] }
        ]
      }
    ]
  }
}

侧边栏(sidebar)

要启用侧边栏,请使用 themeConfig.sidebar。基本配置需要一系列链接:

// .vuepress/config.js
module.exports = {
  themeConfig: {
    sidebar: [
      '/',
      '/page-a',
      ['/page-b', 'Explicit link text']
    ]
  }
}

你可以省略 .md 扩展名,以 / 结尾的路径被推断为 */README.md 。该链接的文本是自动推断的(从页面的第一个标题或 YAML front matter 中的显式标题)。如果你希望明确指定链接文本,请使用 [link,text] 形式的数组。

侧边栏自动显示当前激活页面中标题的链接,嵌套在页面本身的链接下。你可以使用 themeConfig.sidebarDepth 自定义此行为。默认深度是 1,它提取 h2 标题。将其设置为 0 将禁用标题链接,最大值为2,同时提取 h2h3 标题。

页面也可以在使用 YAML front matter 时覆盖此值:

---
sidebarDepth: 2
---

侧边栏组(sidebar groups)

你可以使用对象将侧边栏链接分成多个组:

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

侧边栏组默认情况下是可折叠的。你可以强制一个组始终以 collapsable:false 打开。

多个侧边栏(multiple sidebars)

如果你希望为不同的页面组显示不同的侧边栏,请先将页面组织到目录中:

.
├─ README.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',
        'two'
      ],
      // 侧边栏在 /bar/ 上
      '/bar/': [
        '',
        'three',
        'four'
      ]
    }
  }
}

单页自动补充工具栏(auto sidebar for single pages)

如果你希望自动生成仅包含当前页面的标题链接的侧边栏,则可以在该页面上使用 YAML front matter

---
sidebar: auto
---

禁用侧边栏(disabling the sidebar)

你可以使用 YAML front matter 禁用特定页面上的侧边栏:

---
sidebar: false
---

根据激活页面的侧边栏顺序自动推断上一个和下一个链接。你也可以使用 YAML front matter 来显式覆盖或禁用它们:

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

GitHub 仓库和编辑链接

提供 themeConfig.repo 会在导航栏中自动生成一个 GitHub 链接,并在每个页面的底部显示「编辑此页面」链接。

// .vuepress/config.js
module.exports = {
  themeConfig: {
    // 假定 GitHub。也可以是一个完整的 GitLab 网址
    repo: 'vuejs/vuepress',
    // 如果你的文档不在仓库的根部
    docsDir: 'docs',
    // 可选,默认为 master
    docsBranch: 'master',
    // 默认为 true,设置为 false 来禁用
    editLinks: true
  }
}

简单的 CSS 覆盖

如果你希望对默认主题的样式应用简单覆盖,则可以创建一个 .vuepress/override.styl 文件。 这是 Stylus 文件,但你也可以使用普通的 CSS 语法。

有几个颜色变量可以调整:

// 显示默认值
$accentColor = #3eaf7c
$textColor = #2c3e50
$borderColor = #eaecef
$codeBgColor = #282c34

custom page class

Sometimes, you may need to add a unique class for a specific page so that you can target content on that page only in custom CSS. You can add a class to the theme container div with pageClass in YAML front matter:

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

Then you can write CSS targeting that page only:

.theme-container.custom-page-class {
  /* page-specific rules */
}

特定页面的自定义布局(custom layout for specific pages)

默认情况下,每个 *.md 文件的内容都会显示在一个 <div class =“page”> 容器中,以及侧边栏,自动生成的编辑链接和 prev/next 链接。如果你希望使用完全自定义的组件代替页面(同时只保留导航栏),则可以使用 YAML front matter 再次指定要使用的组件:

---
layout: SpecialLayout
---

这将为给定页面渲染 .vuepress/components/SpecialLayout.vue

Ejecting

You can copy the default theme source code into .vuepress/theme to fully customize the theme using the vuepress eject [targetDir] command. Note, however, once you eject, you are on your own and won’t be receiving future updates or bug fixes to the default theme even if you upgrade VuePress.


原文:https://vuepress.vuejs.org/default-theme-config/