配置
默认主题配置的参考文档，可以通过 themeConfig 来设置这些配置。
基础配置
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：
module.exports = {
themeConfig: {
navbar: [
// NavbarItem
{
text: 'Foo',
link: '/foo/',
},
// NavbarGroup
{
text: 'Group',
children: ['/group/foo.md', '/group/bar.md'],
},
// 字符串 - 页面文件路径
'/bar/README.md',
],
},
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
- 示例 2：
module.exports = {
themeConfig: {
navbar: [
// 嵌套 Group - 最大深度为 2
{
text: 'Group',
children: [
{
text: 'SubGroup',
children: ['/group/sub/foo.md', '/group/sub/bar.md'],
},
],
},
// 控制元素何时被激活
{
text: 'Group 2',
children: [
{
text: 'Always active',
link: '/',
// 该元素将一直处于激活状态
activeMatch: '/',
},
{
text: 'Active on /foo/',
link: '/not-foo/',
// 该元素在当前路由路径是 /foo/ 开头时激活
// 支持正则表达式
activeMatch: '^/foo/',
},
],
},
],
},
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
logo
类型：
null | string详情：
Logo 图片的 URL。
Logo 图片将会显示在导航栏的左端。
设置为
null可以禁用 Logo 。示例：
module.exports = {
themeConfig: {
// Public 文件路径
logo: '/images/hero.png',
// URL
logo: 'https://vuejs.org/images/logo.png',
},
}
2
3
4
5
6
7
8
logoDark
类型：
null | string详情：
在夜间模式中使用的 Logo 图片的 URL。
如果你想在夜间模式中使用不同的 Logo 图片，就可以使用该配置项。
设置为
null可以在夜间模式下禁用 Logo 。忽略该配置项将会在夜间模式中使用 logo 配置。参考：
darkMode
类型：
boolean默认值：
true详情：
是否启用切换夜间模式的功能。
如果设置为
true，将会在导航栏展示一个切换夜间模式的按钮，并会根据 prefers-color-scheme在新窗口打开 自动设置初始模式。
repo
类型：
string详情：
项目仓库的 URL。
它将被用作 仓库链接 的链接。仓库链接 将会显示为导航栏的最后一个元素。
module.exports = {
themeConfig: {
// 如果你按照 `organization/repository` 的格式设置它
// 我们会将它作为一个 GitHub 仓库
repo: 'vuejs/vuepress',
// 你也可以直接将它设置为一个 URL
repo: 'https://gitlab.com/foo/bar',
},
}
2
3
4
5
6
7
8
9
repoLabel
类型：
string详情：
项目仓库的标签。
它将被用作 仓库链接 的文字。仓库链接 将会显示为导航栏的最后一个元素。
如果你不明确指定该配置项，它将会根据 repo 配置项自动推断。
selectLanguageText
类型：
string详情：
选择语言菜单 的文字。
如果你在站点配置中设置了多个 locales ，那么 选择语言菜单 就会显示在导航栏中仓库按钮的旁边。
selectLanguageAriaLabel
类型：
string详情：
选择语言菜单 的
aria-label属性。它主要是为了站点的可访问性 (a11y) 。
selectLanguageName
类型：
string详情：
Locale 的语言名称。
该配置项 仅能在主题配置的 locales 的内部生效 。它将被用作 locale 的语言名称，展示在 选择语言菜单 内。
示例：
module.exports = {
locales: {
'/': {
lang: 'en-US',
},
'/zh/': {
lang: 'zh-CN',
},
},
themeConfig: {
locales: {
'/': {
selectLanguageName: 'English',
},
'/zh/': {
selectLanguageName: '简体中文',
},
},
},
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
sidebar
类型：
false | 'auto' | SidebarConfigArray | SidebarConfigObject默认值：
'auto'详情：
侧边栏配置。
你可以通过页面的 sidebar frontmatter 来覆盖这个全局配置。
设置为
false可以禁用侧边栏。如果你设置为
'auto'，侧边栏会根据页面标题自动生成。为了手动配置侧边栏元素，你可以将其设置为 侧边栏数组 ，其中的每个元素是一个
SidebarItem对象或者一个字符串：SidebarItem对象应该有一个text字段，有一个可选的link字段和一个可选的children字段。children字段同样是一个 侧边栏数组 。- 字符串应为目标页面文件的路径。它将会被转换为
SidebarItem对象，将页面标题作为text，将页面路由路径作为link，并根据页面小标题自动生成children。
如果你想在不同子路径中使用不同的侧边栏，你可以将该配置项设置为 侧边栏对象 ：
- Key 为路径前缀。
- Value 为 侧边栏数组 。
示例 1：
module.exports = {
themeConfig: {
// 侧边栏数组
// 所有页面会使用相同的侧边栏
sidebar: [
// SidebarItem
{
text: 'Foo',
link: '/foo/',
children: [
// SidebarItem
{
text: 'github',
link: 'https://github.com',
children: [],
},
// 字符串 - 页面文件路径
'/foo/bar.md',
],
},
// 字符串 - 页面文件路径
'/bar/README.md',
],
},
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
- 示例 2：
module.exports = {
themeConfig: {
// 侧边栏对象
// 不同子路径下的页面会使用不同的侧边栏
sidebar: {
'/guide/': [
{
text: 'Guide',
children: ['/guide/README.md', '/guide/getting-started.md'],
},
],
'/reference/': [
{
text: 'Reference',
children: ['/reference/cli.md', '/reference/config.md'],
},
],
},
},
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
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 拼接上页面文件的相对路径 示例：
module.exports = {
themeConfig: {
docsRepo: 'https://gitlab.com/owner/name',
docsBranch: 'master',
docsDir: 'docs',
editLinkPattern: ':repo/-/edit/:branch/:path',
},
}
2
3
4
5
6
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 来覆盖这个全局配置。
要注意的是，如果你将
themeConfig.lastUpdated设为了false，那么这个功能会被完全禁用，并且无法在 locales 或页面 frontmatter 中启用。
lastUpdatedText
类型：
string默认值：
'Last Updated'详情：
最近更新时间戳 标签的文字。
contributors
类型：
boolean默认值：
true详情：
是否启用 贡献者列表 。
你可以通过页面的 contributors frontmatter 来覆盖这个全局配置。
要注意的是，如果你将
themeConfig.contributors设为了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
类型：
string默认值：
'open in new window'详情：
OutboundLink 链接内的
sr-only文字。它主要是为了站点的可访问性 (a11y) 。
toggleDarkMode
类型：
string默认值：
'toggle dark mode'详情：
切换夜间模式按钮的标题文字。
它主要是为了站点的可访问性 (a11y) 。
toggleSidebar
类型：
string默认值：
'toggle sidebar'详情：
切换侧边栏按钮的标题文字。
它主要是为了站点的可访问性 (a11y) 。
插件配置
themePlugins
详情：
设置默认主题使用的插件。
默认主题使用了一些插件，如果你确实不需要该插件，你可以选择禁用它。在禁用插件之前，请确保你已了解它的用途。
themePlugins.activeHeaderLinks
类型：
boolean默认值：
true详情：
themePlugins.backToTop
类型：
boolean默认值：
true详情：
是否启用 @vuepress/plugin-back-to-top 。
themePlugins.container
类型：
Record<ContainerType, boolean>详情：
是否启用由 @vuepress/plugin-container 支持的自定义容器。
ContainerType类型为：tipwarningdangerdetailscodeGroupcodeGroupItem
参考：
themePlugins.git
类型：
boolean默认值：
true详情：
是否启用 @vuepress/plugin-git 。
themePlugins.mediumZoom
类型：
boolean默认值：
true详情：
是否启用 @vuepress/plugin-medium-zoom 。
themePlugins.nprogress
类型：
boolean默认值：
true详情：
是否启用 @vuepress/plugin-nprogress 。