配置
基础配置
hostname
类型：
string详情：
部署的域名，例如
https://example.com
locales
类型：
{ [path: string]: Partial<DefaultThemeLocaleData> }默认值：
{}详情：
多语言支持的各个语言 locales 。
所有在 Locale 配置 章节内的配置项都可以在 locales 中使用。
该配置项仅能在默认主题内生效，注意不要和 站点配置 中的
locales混淆。参考：
Locale 配置
该章节内的配置项可以作为一般配置使用，也可以使用在 locales 内。
colorMode
类型：
'auto' | 'light' | 'dark'默认值：
'auto'详情：
默认颜色模式。
如果设置为
'auto'，则会根据 prefers-color-scheme 自动设置初始颜色模式。参考：
colorModeSwitch
类型：
boolean默认值：
true详情：
是否启用切换颜色模式的功能。
如果设置为
true，将会在导航栏展示一个切换颜色模式的按钮。参考：
externalLinkIcon
类型：
boolean默认值：
true详情：
是否在外部链接上显示外部链接图标。
home
类型：
string默认值：
/详情：
首页的路径。
它将被用于：
- 导航栏中 Logo 的链接
- 404 页面的 返回首页 链接
navbar
类型：
false | NavbarOptions默认值：
[]详情：
导航栏配置。
设置为
false可以禁用导航栏。为了配置导航栏元素，你可以将其设置为 导航栏数组 ，其中的每个元素是
NavbarLink对象、NavbarGroup对象、或者字符串：NavbarLink对象应该有一个text字段和一个link字段，还有一个可选的activeMatch字段。NavbarGroup对象应该有一个text字段和一个children字段，还有一个可选的prefix字段。children字段同样是一个 导航栏数组，而prefix会作为 导航栏数组 的路径前缀。- 字符串应为目标页面文件的路径。它将会被转换为
NavbarLink对象，将页面标题作为text，将页面路由路径作为link。
示例 1：
export default {
theme: defaultTheme({
navbar: [
// NavbarLink
{
text: 'Foo',
link: '/foo/',
},
// NavbarGroup
{
text: 'Group',
prefix: '/group/',
children: ['foo.md', 'bar.md'],
},
// 字符串 - 页面文件路径
'/bar/README.md',
],
}),
}- 示例 2：
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/',
},
],
},
],
}),
}logo
类型：
null | string详情：
Logo 图片的 URL。
Logo 图片将会显示在导航栏的左端。
设置为
null可以禁用 Logo 。示例：
export default {
theme: defaultTheme({
// Public 文件路径
logo: '/images/hero.png',
// URL
logo: 'https://vuepress.vuejs.org/images/hero.png',
}),
}logoDark
类型：
null | string详情：
在夜间模式中使用的 Logo 图片的 URL。
如果你想在夜间模式中使用不同的 Logo 图片，就可以使用该配置项。
设置为
null可以在夜间模式下禁用 Logo 。忽略该配置项将会在夜间模式中使用 logo 配置。参考：
logoAlt
类型：
null | string详情：
指定 Logo 图片的替代文字。
当未指定时，将默认与站点标题相同。
repo
类型：
string详情：
项目仓库的 URL。
它将被用作 仓库链接 的链接。仓库链接 将会显示为导航栏的最后一个元素。
export default {
theme: defaultTheme({
// 如果你按照 `organization/repository` 的格式设置它
// 我们会将它作为一个 GitHub 仓库
repo: 'vuepress/core',
// 你也可以直接将它设置为一个 URL
repo: 'https://gitlab.com/foo/bar',
}),
}sidebar
类型：
false | SidebarOptions默认值：
'heading'详情：
侧边栏配置。
你可以通过页面的 sidebar frontmatter 来覆盖这个全局配置。
设置为
false可以禁用侧边栏。如果你设置为
'heading'，侧边栏会根据页面标题自动生成。为了手动配置侧边栏元素，你可以将其设置为 侧边栏数组 ，其中的每个元素是一个
SidebarItem对象或者一个字符串：SidebarItem对象应该有一个text字段，有一个可选的link字段、一个可选的children字段、一个可选的collapsible字段和一个可选的prefix字段。children字段同样是一个 侧边栏数组，prefix会作为每个子项目的路径前缀。collapsible字段来控制它是否可折叠。- 字符串应为目标页面文件的路径。它将会被转换为
SidebarItem对象，将页面标题作为text，将页面路由路径作为link，并根据页面小标题自动生成children。
如果你想在不同子路径中使用不同的侧边栏，你可以将该配置项设置为 侧边栏对象 ：
- Key 为路径前缀。
- Value 为 侧边栏数组 或
"heading"以自动为相应路径生成基于标题的侧边栏。
示例 1：
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',
],
}),
}- 示例 2：
export default {
theme: defaultTheme({
// 侧边栏对象
// 不同子路径下的页面会使用不同的侧边栏
sidebar: {
'/guide/': [
{
text: 'Guide',
// 相对路径会自动追加子路径前缀
children: [
'introduction.md', // 解析为 `/guide/introduction.md`
'getting-started.md', // 解析为 `/guide/getting-started.md`
],
},
],
'/reference/': 'heading',
},
}),
}- 示例 3：
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'],
},
],
},
}),
}sidebarDepth
类型：
number默认值：
2详情：
设置根据页面标题自动生成的侧边栏的最大深度。
- 设为
0来禁用所有级别的页面标题。 - 设为
1来包含<h2>标题。 - 设为
2来包含<h2>和<h3>标题。 - ...
你可以通过页面的 sidebarDepth frontmatter 来覆盖这个全局配置。
- 设为
editLink
类型：
boolean默认值：
true详情：
是否启用 编辑此页 链接。
你可以通过页面的 editLink frontmatter 来覆盖这个全局配置。
editLinkPattern
类型：
string详情：
编辑此页 链接的 Pattern 。
它将会用于生成 编辑此页 的链接。
如果你不设置该选项，则会根据 docsRepo 配置项来推断 Pattern 。但是如果你的文档仓库没有托管在常用的平台上，比如 GitHub 、 GitLab 、 Bitbucket 、 Gitee 等，那么你必须设置该选项才能使 编辑此页 链接正常工作。
用法：
Pattern 描述 :repo文档仓库 URL ，即 docsRepo :branch文档仓库分支 ，即 docsBranch :path页面源文件的路径，即 docsDir 拼接上页面文件的相对路径 示例：
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' 的链接。
docsRepo
类型：
string详情：
文档源文件的仓库 URL 。
它将会用于生成 编辑此页 的链接。
如果你不设置该选项，则默认会使用 repo 配置项。但是如果你的文档源文件是在一个不同的仓库内，你就需要设置该配置项了。
docsBranch
类型：
string默认值：
'main'详情：
文档源文件的仓库分支。
它将会用于生成 编辑此页 的链接。
docsDir
类型：
string默认值：
''详情：
文档源文件存放在仓库中的目录名。
它将会用于生成 编辑此页 的链接。
lastUpdated
类型：
boolean默认值：
true详情：
是否启用 最近更新时间戳 。
你可以通过页面的 lastUpdated frontmatter 来覆盖这个全局配置。要注意的是，如果你已经将该选项设为了
false，那么这个功能会被完全禁用，并且无法在 locales 或页面 frontmatter 中启用。
contributors
类型：
boolean默认值：
true详情：
是否启用 贡献者列表 。
你可以通过页面的 contributors frontmatter 来覆盖这个全局配置。要注意的是，如果你已经将该选项设为了
false，那么这个功能会被完全禁用，并且无法在 locales 或页面 frontmatter 中启用。