配置

基础配置

hostnamestring

部署的域名，例如 https://example.com

locales{ [path: string]: Partial<DefaultThemeLocaleData> }

默认值{}

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

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

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

参考：指南 > 多语言支持

Locale 配置

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

colorMode'auto' | 'light' | 'dark'

默认值'auto'

默认颜色模式。

如果设置为 'auto'，则会根据 prefers-color-scheme 自动设置初始颜色模式。

参考：colorModeSwitch

colorModeSwitchboolean

默认值true

是否启用切换颜色模式的功能。

如果设置为 true，将会在导航栏展示一个切换颜色模式的按钮。

参考：colorMode 与 toggleColorMode

externalLinkIconboolean

默认值true

是否在外部链接上显示外部链接图标。

homestring

默认值/

首页的路径。

它将被用于：

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

false | NavbarOptions

默认值[]

导航栏配置。

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

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

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

.vuepress/config.ts
export default {
  theme: defaultTheme({
    navbar: [
      // NavbarLink
      {
        text: 'Foo',
        link: '/foo/',
      },
      // NavbarGroup
      {
        text: 'Group',
        prefix: '/group/',
        children: ['foo.md', 'bar.md'],
      },
      // 字符串 - 页面文件路径
      '/bar/README.md',
    ],
  }),
}

.vuepress/config.ts
export default {
  theme: defaultTheme({
    navbar: [
      // 嵌套 Group - 最大深度为 2
      {
        text: 'Group',
        prefix: '/group/',
        children: [
          {
            text: 'SubGroup1',
            prefix: 'sub1/',
            children: [
              'foo.md', // 解析为 `/guide/group/sub1/bar.md`
              'bar.md', // 解析为 `/guide/group/sub1/bar.md`

              // 一个外部链接
              {
                text: 'Example',
                link: 'https://example.com',
              },
            ],
          },
          {
            text: 'SubGroup2',
            prefix: 'sub2/',
            // 项目内链接的 .md 或 .html 后缀是可以省略的
            children: [
              'foo', // 解析为 `/guide/group/sub2/foo.md`
              'bar', // 解析为 `/guide/group/sub2/bar.md`

              // 不在 SubGroup2 内的链接
              '/baz/', // 解析为 `/baz/README.md`
            ],
          },
        ],
      },
      // 控制元素何时被激活
      {
        text: 'Group 2',
        children: [
          {
            text: 'Always active',
            link: '/',
            // 该元素将一直处于激活状态
            activeMatch: '/',
          },
          {
            text: 'Active on /foo/',
            link: '/not-foo/',
            // 该元素在当前路由路径是 /foo/ 开头时激活
            // 支持正则表达式
            activeMatch: '^/foo/',
          },
        ],
      },
    ],
  }),
}

logonull | string

Logo 图片的 URL。

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

设置为 null 可以禁用 Logo。

.vuepress/config.ts
export default {
  theme: defaultTheme({
    // Public 文件路径
    logo: '/images/hero.png',
    // URL
    logo: 'https://vuepress.vuejs.org/images/hero.png',
  }),
}

参考：指南 > 静态资源 > Public 文件

logoDarknull | string

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

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

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

参考：colorMode

logoAltnull | string

指定 Logo 图片的替代文字。

当未指定时，将默认与站点标题相同。

repostring

项目仓库的 URL。

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

.vuepress/config.ts
export default {
  theme: defaultTheme({
    // 如果你按照 `organization/repository` 的格式设置它
    // 我们会将它作为一个 GitHub 仓库
    repo: 'vuepress/core',
    // 你也可以直接将它设置为一个 URL
    repo: 'https://gitlab.com/foo/bar',
  }),
}

false | SidebarOptions

默认值'heading'

侧边栏配置。

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

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

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

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

SidebarItem 对象应该有一个 text 字段，有一个可选的 link 字段、一个可选的 children 字段、一个可选的 collapsible 字段和一个可选的 prefix 字段。children 字段同样是一个 侧边栏数组，prefix 会作为每个子项目的路径前缀。collapsible 字段来控制它是否可折叠。
字符串应为目标页面文件的路径。它将会被转换为 SidebarItem 对象，将页面标题作为 text，将页面路由路径作为 link，并根据页面小标题自动生成 children。

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

Key 为路径前缀。
Value 为 侧边栏数组 或 "heading" 以自动为相应路径生成基于标题的侧边栏。

.vuepress/config.ts
export default {
  theme: defaultTheme({
    // 侧边栏数组
    // 所有页面会使用相同的侧边栏
    sidebar: [
      // SidebarItem
      {
        text: 'Foo',
        prefix: '/foo/',
        link: '/foo/',
        children: [
          // SidebarItem
          {
            text: 'github',
            link: 'https://github.com',
            children: [],
          },
          // 字符串 - 页面文件路径
          'bar.md', // 解析为 `/foo/bar.md`
          '/ray.md', // 解析为 `/ray.md`
        ],
      },
      // 字符串 - 页面文件路径
      '/bar/README.md',
    ],
  }),
}

.vuepress/config.ts
export default {
  theme: defaultTheme({
    // 侧边栏对象
    // 不同子路径下的页面会使用不同的侧边栏
    sidebar: {
      '/guide/': [
        {
          text: 'Guide',
          // 相对路径会自动追加子路径前缀
          children: [
            'introduction.md', // 解析为 `/guide/introduction.md`
            'getting-started.md', // 解析为 `/guide/getting-started.md`
          ],
        },
      ],
      '/reference/': 'heading',
    },
  }),
}

.vuepress/config.ts
export default {
  theme: defaultTheme({
    // 可折叠的侧边栏
    sidebar: {
      '/reference/': [
        {
          text: 'VuePress Reference',
          collapsible: true,
          // 基于项目路径的 .md 或 .html 后缀是可以省略的
          children: ['cli', 'config'],
        },
        {
          text: 'Bundlers Reference',
          collapsible: true,
          // 前缀可以是相对路径，等同于 `prefix: /reference/bundler/`
          prefix: 'bundler/',
          children: ['vite', 'webpack'],
        },
      ],
    },
  }),
}

sidebarDepthnumber

默认值2

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

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

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

editLinkboolean

默认值true

是否启用 编辑此页 链接。

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

editLinkPatternstring

编辑此页 链接的 Pattern。

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

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

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

.vuepress/config.ts
export default {
  theme: defaultTheme({
    docsRepo: 'https://gitlab.com/owner/name',
    docsBranch: 'master',
    docsDir: 'docs',
    editLinkPattern: ':repo/-/edit/:branch/:path',
  }),
}

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

docsRepostring

文档源文件的仓库 URL。

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

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

docsBranchstring

默认值'main'

文档源文件的仓库分支。

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

docsDirstring

默认值''

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

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

lastUpdatedboolean

默认值true

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

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

contributorsboolean

默认值true

是否启用 贡献者列表。

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