配置

  1. const { defaultTheme } = require('@vuepress/theme-default')
  3. module.exports = {
  4.   theme: defaultTheme({
  5.     // 在这里进行配置
  6.   }),
  7. }

基础配置

locales

  • 类型： { [path: string]: Partial<DefaultThemeLocaleData> }

  • 默认值： {}

  • 详情：

    多语言支持的各个语言 locales 。

    所有在 Locale 配置 章节内的配置项都可以在 locales 中使用。

    该配置项仅能在默认主题内生效，注意不要和 站点配置 中的 locales 混淆。

  • 参考：

Locale 配置

该章节内的配置项可以作为一般配置使用，也可以使用在 locales 内。

home

  • 类型： string

  • 默认值： /

  • 详情：

    首页的路径。

    它将被用于：

    • 导航栏中 Logo 的链接
    • 404 页面的 返回首页 链接

navbar

  • 类型： false | (NavbarItem | NavbarGroup | string)[]

  • 默认值： []

  • 详情：

    导航栏配置。

    设置为 false 可以禁用导航栏。

    为了配置导航栏元素，你可以将其设置为 导航栏数组 ，其中的每个元素是 NavbarItem 对象、 NavbarGroup 对象、或者字符串：

    • NavbarItem 对象应该有一个 text 字段和一个 link 字段，还有一个可选的 activeMatch 字段。
    • NavbarGroup 对象应该有一个 text 字段和一个 children 字段。 children 字段同样是一个 导航栏数组 。
    • 字符串应为目标页面文件的路径。它将会被转换为 NavbarItem 对象，将页面标题作为 text ，将页面路由路径作为 link 。

  • 示例 1：

  1. module.exports = {
  2.   theme: defaultTheme({
  3.     navbar: [
  4.       // NavbarItem
  5.       {
  6.         text: 'Foo',
  7.         link: '/foo/',
  8.       },
  9.       // NavbarGroup
  10.       {
  11.         text: 'Group',
  12.         children: ['/group/foo.md', '/group/bar.md'],
  13.       },
  14.       // 字符串 - 页面文件路径
  15.       '/bar/README.md',
  16.     ],
  17.   }),
  18. }
  • 示例 2：
  1. module.exports = {
  2.   theme: defaultTheme({
  3.     navbar: [
  4.       // 嵌套 Group - 最大深度为 2
  5.       {
  6.         text: 'Group',
  7.         children: [
  8.           {
  9.             text: 'SubGroup',
  10.             children: ['/group/sub/foo.md', '/group/sub/bar.md'],
  11.           },
  12.         ],
  13.       },
  14.       // 控制元素何时被激活
  15.       {
  16.         text: 'Group 2',
  17.         children: [
  18.           {
  19.             text: 'Always active',
  20.             link: '/',
  21.             // 该元素将一直处于激活状态
  22.             activeMatch: '/',
  23.           },
  24.           {
  25.             text: 'Active on /foo/',
  26.             link: '/not-foo/',
  27.             // 该元素在当前路由路径是 /foo/ 开头时激活
  28.             // 支持正则表达式
  29.             activeMatch: '^/foo/',
  30.           },
  31.         ],
  32.       },
  33.     ],
  34.   }),
  35. }

logo

  • 类型： null | string

  • 详情：

    Logo 图片的 URL。

    Logo 图片将会显示在导航栏的左端。

    设置为 null 可以禁用 Logo 。

  • 示例：

  1. module.exports = {
  2.   theme: defaultTheme({
  3.     // Public 文件路径
  4.     logo: '/images/hero.png',
  5.     // URL
  6.     logo: 'https://vuejs.org/images/logo.png',
  7.   }),
  8. }

logoDark

  • 类型： null | string

  • 详情：

    在夜间模式中使用的 Logo 图片的 URL。

    如果你想在夜间模式中使用不同的 Logo 图片，就可以使用该配置项。

    设置为 null 可以在夜间模式下禁用 Logo 。忽略该配置项将会在夜间模式中使用 logo 配置。

  • 参考：

darkMode

  • 类型： boolean

  • 默认值： true

  • 详情：

    是否启用切换夜间模式的功能。

    如果设置为 true ，将会在导航栏展示一个切换夜间模式的按钮，并会根据 prefers-color-scheme 自动设置初始模式。

repo

  • 类型： string

  • 详情：

    项目仓库的 URL。

    它将被用作 仓库链接 的链接。仓库链接 将会显示为导航栏的最后一个元素。

  1. module.exports = {
  2.   theme: defaultTheme({
  3.     // 如果你按照 `organization/repository` 的格式设置它
  4.     // 我们会将它作为一个 GitHub 仓库
  5.     repo: 'vuejs/vuepress',
  6.     // 你也可以直接将它设置为一个 URL
  7.     repo: 'https://gitlab.com/foo/bar',
  8.   }),
  9. }

repoLabel

  • 类型： string

  • 详情：

    项目仓库的标签。

    它将被用作 仓库链接 的文字。仓库链接 将会显示为导航栏的最后一个元素。

    如果你不明确指定该配置项，它将会根据 repo 配置项自动推断。

selectLanguageText

  • 类型： string

  • 详情：

    选择语言菜单 的文字。

    如果你在站点配置中设置了多个 locales ，那么 选择语言菜单 就会显示在导航栏中仓库按钮的旁边。

selectLanguageAriaLabel

  • 类型： string

  • 详情：

    选择语言菜单 的 aria-label 属性。

    它主要是为了站点的可访问性 (a11y) 。

selectLanguageName

  • 类型： string

  • 详情：

    Locale 的语言名称。

    该配置项 仅能在主题配置的 locales 的内部生效 。它将被用作 locale 的语言名称，展示在 选择语言菜单 内。

  • 示例：

  1. module.exports = {
  2.   locales: {
  3.     '/': {
  4.       lang: 'en-US',
  5.     },
  6.     '/zh/': {
  7.       lang: 'zh-CN',
  8.     },
  9.   },
  10.   theme: defaultTheme({
  11.     locales: {
  12.       '/': {
  13.         selectLanguageName: 'English',
  14.       },
  15.       '/zh/': {
  16.         selectLanguageName: '简体中文',
  17.       },
  18.     },
  19.   }),
  20. }

sidebar

  • 类型： false | 'auto' | SidebarConfigArray | SidebarConfigObject

  • 默认值： 'auto'

  • 详情：

    侧边栏配置。

    你可以通过页面的 sidebar frontmatter 来覆盖这个全局配置。

    设置为 false 可以禁用侧边栏。

    如果你设置为 'auto'，侧边栏会根据页面标题自动生成。

    为了手动配置侧边栏元素，你可以将其设置为 侧边栏数组 ，其中的每个元素是一个 SidebarItem 对象或者一个字符串：

    • SidebarItem 对象应该有一个 text 字段，有一个可选的 link 字段和一个可选的 children 字段。 children 字段同样是一个 侧边栏数组 。当 SidebarItem 对象处于根节点时，它还有一个额外可选的 collapsible 字段来控制它是否可折叠。
    • 字符串应为目标页面文件的路径。它将会被转换为 SidebarItem 对象，将页面标题作为 text ，将页面路由路径作为 link ，并根据页面小标题自动生成 children 。

    如果你想在不同子路径中使用不同的侧边栏，你可以将该配置项设置为 侧边栏对象 ：

    • Key 为路径前缀。
    • Value 为 侧边栏数组 。

  • 示例 1：

  1. module.exports = {
  2.   theme: defaultTheme({
  3.     // 侧边栏数组
  4.     // 所有页面会使用相同的侧边栏
  5.     sidebar: [
  6.       // SidebarItem
  7.       {
  8.         text: 'Foo',
  9.         link: '/foo/',
  10.         children: [
  11.           // SidebarItem
  12.           {
  13.             text: 'github',
  14.             link: 'https://github.com',
  15.             children: [],
  16.           },
  17.           // 字符串 - 页面文件路径
  18.           '/foo/bar.md',
  19.         ],
  20.       },
  21.       // 字符串 - 页面文件路径
  22.       '/bar/README.md',
  23.     ],
  24.   }),
  25. }
  • 示例 2：
  1. module.exports = {
  2.   theme: defaultTheme({
  3.     // 侧边栏对象
  4.     // 不同子路径下的页面会使用不同的侧边栏
  5.     sidebar: {
  6.       '/guide/': [
  7.         {
  8.           text: 'Guide',
  9.           children: ['/guide/README.md', '/guide/getting-started.md'],
  10.         },
  11.       ],
  12.       '/reference/': [
  13.         {
  14.           text: 'Reference',
  15.           children: ['/reference/cli.md', '/reference/config.md'],
  16.         },
  17.       ],
  18.     },
  19.   }),
  20. }
  • 示例 3：
  1. module.exports = {
  2.   theme: defaultTheme({
  3.     // 可折叠的侧边栏
  4.     sidebar: {
  5.       '/reference/': [
  6.         {
  7.           text: 'VuePress Reference',
  8.           collapsible: true,
  9.           children: ['/reference/cli.md', '/reference/config.md'],
  10.         },
  11.         {
  12.           text: 'Bundlers Reference',
  13.           collapsible: true,
  14.           children: ['/reference/bundler/vite.md', '/reference/bundler/webpack.md'],
  15.         },
  16.       ],
  17.     },
  18.   }),
  19. }

sidebarDepth

  • 类型： number

  • 默认值： 2

  • 详情：

    设置根据页面标题自动生成的侧边栏的最大深度。

    • 设为 0 来禁用所有级别的页面标题。
    • 设为 1 来包含 <h2> 标题。
    • 设为 2 来包含 <h2> 和 <h3> 标题。
    • …

    最大值取决于你通过 markdown.extractHeaders.level 提取了哪些级别的标题。

    由于 markdown.extractHeaders.level 的默认值是 [2, 3] ，因此 sidebarDepth 的默认最大值是 2 。

    你可以通过页面的 sidebarDepth frontmatter 来覆盖这个全局配置。

editLink

  • 类型： boolean

  • 默认值： true

  • 详情：

    是否启用 编辑此页 链接。

    你可以通过页面的 editLink frontmatter 来覆盖这个全局配置。

editLinkText

  • 类型： string

  • 默认值： 'Edit this page'

  • 详情：

    编辑此页 链接的文字。

editLinkPattern

  • 类型： string

  • 详情：

    编辑此页 链接的 Pattern 。

    它将会用于生成 编辑此页 的链接。

    如果你不设置该选项，则会根据 docsRepo 配置项来推断 Pattern 。但是如果你的文档仓库没有托管在常用的平台上，比如 GitHub 、 GitLab 、 Bitbucket 、 Gitee 等，那么你必须设置该选项才能使 编辑此页 链接正常工作。

  • 用法：

    | Pattern | 描述 | | ————- | ————————————————————————————————- | | :repo | 文档仓库 URL ，即 docsRepo | | :branch | 文档仓库分支 ，即 docsBranch | | :path | 页面源文件的路径，即 docsDir 拼接上页面文件的相对路径 |

  • 示例：

  1. module.exports = {
  2.   theme: defaultTheme({
  3.     docsRepo: 'https://gitlab.com/owner/name',
  4.     docsBranch: 'master',
  5.     docsDir: 'docs',
  6.     editLinkPattern: ':repo/-/edit/:branch/:path',
  7.   }),
  8. }

则会生成类似于 'https://gitlab.com/owner/name/-/edit/master/docs/path/to/file.md' 的链接。

docsRepo

  • 类型： string

  • 详情：

    文档源文件的仓库 URL 。

    它将会用于生成 编辑此页 的链接。

    如果你不设置该选项，则默认会使用 repo 配置项。但是如果你的文档源文件是在一个不同的仓库内，你就需要设置该配置项了。

docsBranch

  • 类型： string

  • 默认值： 'main'

  • 详情：

    文档源文件的仓库分支。

    它将会用于生成 编辑此页 的链接。

docsDir

  • 类型： string

  • 默认值： ''

  • 详情：

    文档源文件存放在仓库中的目录名。

    它将会用于生成 编辑此页 的链接。

lastUpdated

  • 类型： boolean

  • 默认值： true

  • 详情：

    是否启用 最近更新时间戳 。

    你可以通过页面的 lastUpdated frontmatter 来覆盖这个全局配置。要注意的是，如果你已经将该选项设为了 false ，那么这个功能会被完全禁用，并且无法在 locales 或页面 frontmatter 中启用。

lastUpdatedText

  • 类型： string

  • 默认值： 'Last Updated'

  • 详情：

    最近更新时间戳 标签的文字。

contributors

  • 类型： boolean

  • 默认值： true

  • 详情：

    是否启用 贡献者列表 。

    你可以通过页面的 contributors frontmatter 来覆盖这个全局配置。要注意的是，如果你已经将该选项设为了 false ，那么这个功能会被完全禁用，并且无法在 locales 或页面 frontmatter 中启用。

contributorsText

  • 类型： string

  • 默认值： 'Contributors'

  • 详情：

    贡献者列表 标签的文字。

tip

  • 类型： string

  • 默认值： 'TIP'

  • 详情：

    Tip 自定义容器 的默认标题。

warning

  • 类型： string

  • 默认值： 'WARNING'

  • 详情：

    Warning 自定义容器 的默认标题。

danger

  • 类型： string

  • 默认值： 'DANGER'

  • 详情：

    Danger 自定义容器 的默认标题。

notFound

  • 类型： string[]

  • 默认值： ['Not Found']

  • 详情：

    404 页面的提示信息。

    当用户进入 404 页面时，会从数组中随机选取一条信息进行展示。

backToHome

  • 类型： string

  • 默认值： 'Back to home'

  • 详情：

    404 页面中 返回首页 链接的文字。

openInNewWindow

toggleDarkMode

  • 类型： string

  • 默认值： 'toggle dark mode'

  • 详情：

    切换夜间模式按钮的标题文字。

    它主要是为了站点的可访问性 (a11y) 。

toggleSidebar

  • 类型： string

  • 默认值： 'toggle sidebar'

  • 详情：

    切换侧边栏按钮的标题文字。

    它主要是为了站点的可访问性 (a11y) 。

插件配置

themePlugins

  • 详情：

    设置默认主题使用的插件。

    默认主题使用了一些插件，如果你确实不需要该插件，你可以选择禁用它。在禁用插件之前，请确保你已了解它的用途。

themePlugins.activeHeaderLinks

themePlugins.backToTop

themePlugins.container

themePlugins.externalLinkIcon

themePlugins.git

themePlugins.mediumZoom

themePlugins.nprogress