主题 配置
This configuration applies to all main themes.
通用
色彩模式
经典主题默认提供浅色主题和暗黑主题,用户可以通过导航栏切换。
可以通过 colorMode
对象自定义色彩模式支持。
接受的字段:
参数 | 类型 | 默认值 | 描述 |
---|---|---|---|
defaultMode | 'light' | 'dark' | 'light' | 用户首次访问网站时的色彩模式。 |
disableSwitch | boolean | false | 在导航栏隐藏按钮。 如果你想要只支持一种色彩模式很有用。 |
respectPrefersColorScheme | boolean | false | 是否使用 prefers-color-scheme 媒体查询,从而使用用户系统的首选项,而不是硬代码的 defaultMode 。 |
示例配置:
module.exports = {
themeConfig: {
colorMode: {
defaultMode: 'light',
disableSwitch: false,
respectPrefersColorScheme: false,
},
},
};
如果使用 respectPrefersColorScheme: true
,defaultMode
会被用户系统的偏好设置覆盖。
如果你只想支持一种色彩模式,你大概率会想要忽略用户系统的偏好设置。
元数据图像
你可以配置用于元标签的默认图像,尤其是 og:image
和 twitter:image
。
接受的字段:
参数 | 类型 | 默认值 | 描述 |
---|---|---|---|
image | string | undefined | 网站的元数据图像 URL。 相对于你的网站的静态目录。 不能是 SVG。 可以是外部链接。 |
示例配置:
module.exports = {
themeConfig: {
image: 'img/docusaurus.png',
},
};
元数据
你可以配置额外的 HTML 元数据(以及覆盖现有数据)。
接受的字段:
参数 | 类型 | 默认值 | 描述 |
---|---|---|---|
metadata | Metadata[] | [] | 所有字段都会被直接传递给 <meta /> 标签。 可选的字段包括 id 、name 、property 、content 、itemprop 等。 |
示例配置:
module.exports = {
themeConfig: {
metadata: [{name: 'twitter:card', content: 'summary'}],
},
};
告示条
有时候,你需要在网站上发布告示。 这种情况下,你可以添加一个告示条。 这是位于导航栏上方的一个面板,非固定而且可以关闭。 所有配置都在 announcementBar
对象中。
接受的字段:
参数 | 类型 | 默认值 | 描述 |
---|---|---|---|
id | string | 'announcement-bar' | 任何能够唯一标识此信息的值。 |
content | string | '' | 告示的文字内容。 HTML 也可以识别。 |
backgroundColor | string | '#fff' | 告示条的背景颜色。 |
textColor | string | '#000' | 告示的文字颜色。 |
isCloseable | boolean | true | 是否可以用 '×' 按钮关闭告示。 |
示例配置:
module.exports = {
themeConfig: {
announcementBar: {
id: 'support_us',
content:
'我们正打算翻新文档,请填写<a target="_blank" rel="noopener noreferrer" href="#">这个调查</a>',
backgroundColor: '#fafbfc',
textColor: '#091E42',
isCloseable: false,
},
},
};
导航栏
接受的字段:
参数 | 类型 | 默认值 | 描述 |
---|---|---|---|
title | string | undefined | 导航栏标题。 |
logo | 见下文 | undefined | 图标对象的自定义。 |
items | NavbarItem[] | [] | 导航栏项目列表。 见下文的说明。 |
hideOnScroll | boolean | false | 当用户向下滚动时,导航栏是否隐藏。 |
style | 'primary' | 'dark' | 与色彩模式一致 | 设置导航栏样式,忽略暗黑/浅色色彩模式。 |
导航栏图标
The logo can be placed in static folder. 图标链接的 URL 会被默认设置为网站的 base URL。 尽管你可以为图标指定自己的 URL,但如果链接是外部的,它会打开一个新标签页。 此外,你还可以覆盖图标链接的 target 属性值,如果你把文档网站托管在主网站的一个子目录中,这个配置会很有用。这种情况下,你可能不需要在链接到主网站的时候打开新标签页。
为了改善暗黑模式支持,你也可以为暗黑模式设置一个不同的图标。
接受的字段:
参数 | 类型 | 默认值 | 描述 |
---|---|---|---|
alt | string | undefined | 图片的 alt 属性。 |
src | string | 必填 | 图片的 URL。 Base URL 会被默认添加。 |
srcDark | string | logo.src | 暗黑模式下使用的替代图像 URL。 |
href | string | siteConfig.baseUrl | 点击图标时跳转到的链接。 |
width | string | number | undefined | 指定 width 属性。 |
height | string | number | undefined | 指定 height 属性。 |
target | string | 根据 href 计算(外部链接会在新标签页中打开,其他链接在本页中打开) | 链接的 target 属性。控制了链接会在新标签页还是当前页中打开。 |
className | string | undefined | 图片的 CSS 类名。 |
style | object | undefined | 内联 CSS 样式对象。 React/JSX 风格,所有属性都是驼峰格式 (camelCase)。 |
示例配置:
module.exports = {
themeConfig: {
navbar: {
title: '网站标题',
logo: {
alt: 'Site Logo',
src: 'img/logo.svg',
srcDark: 'img/logo_dark.svg',
href: 'https://docusaurus.io/',
target: '_self',
width: 32,
height: 32,
className: 'custom-navbar-logo-class',
style: {border: 'solid red'},
},
},
},
};
导航栏项目
你可以通过向导航栏 themeConfig.navbar.items
添加项目。
module.exports = {
themeConfig: {
navbar: {
items: [
{
type: 'doc',
position: 'left',
docId: 'introduction',
label: '文档',
},
{to: 'blog', label: '博客', position: 'left'},
{
type: 'docsVersionDropdown',
position: 'right',
},
{
type: 'localeDropdown',
position: 'right',
},
{
href: 'https://github.com/facebook/docusaurus',
position: 'right',
className: 'header-github-link',
'aria-label': 'GitHub 仓库',
},
],
},
},
};
根据 type
字段,导航栏项目的行为可能不同。 下面的部分会为你介绍所有的导航栏项目类型。
导航栏链接
导航栏项目默认是一个普通链接(内部或外部均可)。
React Router 会自动给链接应用活跃样式,但在边缘情况下,你可以使用 activeBasePath
。 对于链接应该在几个不同路径上激活的情况(比如你在同一个侧边栏下有多个文件夹), 你可以使用 activeBaseRegex
。 activeBaseRegex
是一个比 activeBasePath
更灵活的替代选项,并且优先于后者——Docusaurus 会把它作为正则表达式解析,并与当前的 URL 匹配。
外部链接会自动获得 target="_blank" rel="noopener noreferrer"
属性。
接受的字段:
参数 | 类型 | 默认值 | 描述 |
---|---|---|---|
type | 'default' | 可选 | 把这个项目的类型设置为链接。 |
label | string | 必填 | 项目显示的名称。 |
html | string | 可选 | 和 label 一样,但渲染纯 HTML 而不是文字内容。 |
to | string | 必填 | 客户端路由,用于站内导航。 会自动在开头添加 base URL。 |
href | string | 必填 | 整页导航,用于站外跳转。 只能使用 to 或 href 中的一个。 |
prependBaseUrlToHref | boolean | false | 在 href 前添加 base URL。 |
position | 'left' | 'right' | 'left' | 项目应该出现在导航栏的哪一侧。 |
activeBasePath | string | to / href | 在以此路径开始的所有路由上应用活跃类样式。 通常没有必要设置。 |
activeBaseRegex | string | undefined | 如果有需要,可以替代 activeBasePath 。 |
className | string | '' | 自定义 CSS 类(用于任何项目的样式)。 |
除了上面的字段外,你可以指定其他任何 HTML 链接接受的属性。
示例配置:
module.exports = {
themeConfig: {
navbar: {
items: [
{
to: 'docs/introduction',
// "to" 和 "href" 只应该用一个
// href: 'https://www.facebook.com',
label: '引言',
// Only one of "label" or "html" should be used
// html: '<b>引言</b>'
position: 'left',
activeBaseRegex: 'docs/(next|v8)',
target: '_blank',
},
],
},
},
};