13 KiB
配置
默认主题配置的参考文档，可以通过 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字段。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：
module.exports = {
themeConfig: {
navbar: [
// 嵌套 Group - 最大深度为 2
{
text: 'Group',
children: [
{
text: 'SubGroup',
children: ['/group/sub/foo.md', '/group/sub/bar.md'],
},
],
},
],
},
}
logo
-
类型：
string -
详情：
Logo 图片的 URL。
Logo 图片将会显示在导航栏的左端。
-
示例：
module.exports = {
themeConfig: {
// Public 文件路径
logo: '/hero.png',
// URL
logo: 'https://vuejs.org/images/logo.png',
},
}
repo
-
类型：
string -
详情：
项目仓库的 URL。
它将被用作 仓库链接 的链接。仓库链接 将会显示为导航栏的最后一个元素。
module.exports = {
themeConfig: {
// 如果你按照 `organization/repository` 的格式设置它
// 我们会将它作为一个 GitHub 仓库
repo: 'vuejs/vuepress',
// 如果你使用的不是 GitHub ，可以直接使用 URL
repo: 'https://gitlab.com/foo/bar',
},
}
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: '简体中文',
},
},
},
}
sidebar
-
类型：
false | 'auto' | SidebarConfigArray | SidebarConfigObject -
默认值：
'auto' -
详情：
侧边栏配置。
你可以通过页面的 sidebar frontmatter 来覆盖这个全局配置。
设置为
false可以禁用侧边栏。如果你设置为
'auto'，侧边栏会根据页面标题自动生成。为了手动配置侧边栏元素，你可以将其设置为 侧边栏数组 ，其中的每个元素是
SidebarItem对象、SidebarGroup对象、或者字符串：SidebarItem对象应该有一个text字段、一个link字段和一个children字段。children字段是一个由SidebarItem或者字符串组成的数组。SidebarGroup对象应将isGroup字段设为true，并且应该有一个text字段和一个children字段。children字段是一个由SidebarItem或者字符串组成的数组。- 字符串应为目标页面文件的路径。它将会被转换为
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',
],
},
// SidebarGroup
{
isGroup: true,
text: 'Group',
children: ['/group/foo.md', '/group/bar.md'],
},
// 字符串 - 页面文件路径
'/bar/README.md',
],
},
}
- 示例 2：
module.exports = {
themeConfig: {
// 侧边栏对象
// 不同子路径下的页面会使用不同的侧边栏
sidebar: {
'/guide/': [
{
isGroup: true,
text: 'Guide',
children: ['/guide/README.md', '/guide/getting-started.md'],
},
],
'/reference/': [
{
isGroup: true,
text: 'Reference',
children: ['/reference/cli.md', '/reference/config.md'],
},
],
},
},
}
editLink
-
类型：
boolean -
默认值：
true -
详情：
是否启用 编辑此页 链接。
你可以通过页面的 editLink frontmatter 来覆盖这个全局配置。
editLinkText
-
类型：
string -
默认值：
'Edit this page' -
详情：
编辑此页 链接的文字。
editLinkPattern
-
类型：
string -
详情：
编辑此页 链接的 Pattern 。
它将会用于生成 编辑此页 的链接。
如果你不设置该选项，则会根据 docsRepo 配置项来推断 Pattern 。但是如果你的文档仓库没有托管在常用的平台上，比如 GitHub 、 GitLab 、 Bitbucket 等，那么你必须设置该选项才能使 编辑此页 链接正常工作。
-
用法：
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',
},
}
则会生成类似于 '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 -
默认值：
'WARNING' -
详情：
Danger 自定义容器 的默认标题。
notFound
-
类型：
string[] -
默认值：
['Not Found'] -
详情：
404 页面的提示信息。
当用户进入 404 页面时，会从数组中随机选取一条信息进行展示。
backToHome
-
类型：
string -
默认值：
'Back to home' -
详情：
404 页面中 返回首页 链接的文字。
openInNewWindow
-
类型：
string -
默认值：
'open in new window' -
详情：
OutboundLink 链接内的
sr-only文字。它主要是为了站点的可访问性 (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.debug
-
类型：
boolean -
默认值：
true -
详情：
是否启用 @vuepress/plugin-debug 。
themePlugins.git
-
类型：
boolean -
默认值：
true -
详情：
是否启用 @vuepress/plugin-git 。
themePlugins.mediumZoom
-
类型：
boolean -
默认值：
true -
详情：
是否启用 @vuepress/plugin-medium-zoom 。
themePlugins.nprogress
-
类型：
boolean -
默认值：
true -
详情：
是否启用 @vuepress/plugin-nprogress 。