主题配置
此配置适用于所有的主要主题。
通用
色彩模式
经典主题默认提供浅色主题和暗黑主题,用户可以通过导航栏切换。
可以通过 colorMode
对象自定义色彩模式支持。
接受的字段:
Name | Type | Default | Description |
---|---|---|---|
defaultMode | 'light' | 'dark' | 'light' | The color mode when user first visits the site. |
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 | 网站的元数据图像链接。 相对于你的网站的静态目录。 不能是 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,
},
},
};
导航栏
接受的字段:
Name | Type | Default | Description |
---|---|---|---|
title | string | undefined | Title for the navbar. |
logo | See below | undefined | Customization of the logo object. |
items | NavbarItem[] | [] | A list of navbar items. 见下文的说明。 |
hideOnScroll | boolean | false | Whether the navbar is hidden when the user scrolls down. |
style | 'primary' | 'dark' | Same as theme | Sets the navbar style, ignoring the dark/light theme. |
导航栏图标
图标可以放在静态文件夹里。 图标链接的 URL 会被默认设置为网站的 base URL。 尽管你可以为图标指定自己的 URL,但如果链接是外部的,它会打开一个新标签页。 此外,你还可以覆盖图标链接的 target 属性值,如果你把文档网站托管在主网站的一个子目录中,这个配置会很有用。这种情况下,你可能不需要在链接到主网站的时候打开新标签页。
为了改善暗黑模式支持,你也可以为暗黑模式设置一个不同的图标。
接受的字段:
Name | Type | Default | Description |
---|---|---|---|
alt | string | undefined | Alt tag for the logo image. |
src | string | Required | URL to the logo image. Base URL 会被默认添加。 |
srcDark | string | logo.src | An alternative image URL to use in dark mode. |
href | string | siteConfig.baseUrl | Link to navigate to when the logo is clicked. |
width | string | number | undefined | Specifies the width attribute. |
height | string | number | undefined | Specifies the height attribute. |
target | string | Calculated based on href (external links will open in a new tab, all others in the current one). | The target attribute of the link; controls whether the link is opened in a new tab, the current one, or otherwise. |
示例配置:
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,
},
},
},
};
导航栏项目
你可以通过向导航栏 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"
属性。
接受的字段:
Name | Type | Default | Description |
---|---|---|---|
type | 'default' | Optional | Sets the type of this item to a link. |
label | string | Required | The name to be shown for this item. |
html | string | Optional | Same as label , but renders pure HTML instead of text content. |
to | string | Required | Client-side routing, used for navigating within the website. 会自动在开头添加 base URL。 |
href | string | Required | A full-page navigation, used for navigating outside of the website. Only one of to or href should be used. |
prependBaseUrlToHref | boolean | false | Prepends the baseUrl to href values. |
position | 'left' | 'right' | 'left' | The side of the navbar this item should appear on. |
activeBasePath | string | to / href | To apply the active class styling on all routes starting with this path. 通常没有必要设置。 |
activeBaseRegex | string | undefined | Alternative to activeBasePath if required. |
className | string | '' | Custom CSS class (for styling any item). |
除了上面的字段外,你可以指定其他任何 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',
},
],
},
},
};
导航栏下拉菜单
dropdown
类型的导航栏项有一个额外的 items
字段,一组内部的导航栏项目。
下拉菜单的内部项目只支持以下「类链接」的项目类型:
请注意下拉菜单的主项也是一个可点击的链接,所以它可以接受普通导航栏链接的任何属性。
接受的字段:
Name | Type | Default | Description |
---|---|---|---|
type | 'dropdown' | Optional | Sets the type of this item to a dropdown. |
label | string | Required | The name to be shown for this item. |
items | LinkLikeItem[] | Required | The items to be contained in the dropdown. |
position | 'left' | 'right' | 'left' | The side of the navbar this item should appear on. |
示例配置:
module.exports = {
themeConfig: {
navbar: {
items: [
{
type: 'dropdown',
label: '社区',
position: 'left',
items: [
{
label: 'Facebook',
href: 'https://www.facebook.com',
},
{
type: 'doc',
label: '社交',
docId: 'social',
},
// ... more items
],
},
],
},
},
};
导航栏文档链接
如果你想要链接到某篇指定文档,这个特别的导航栏项目类型会渲染一个链接,指向带有给定的 docId
的文档。 只要你在浏览同一侧边栏的文档,它就会获得 navbar__link--active
类名。
接受的字段:
Name | Type | Default | Description |
---|---|---|---|
type | 'doc' | Required | Sets the type of this item to a doc link. |
docId | string | Required | The ID of the doc that this item links to. |
label | string | docId | The name to be shown for this item. |
position | 'left' | 'right' | 'left' | The side of the navbar this item should appear on. |
docsPluginId | string | 'default' | The ID of the docs plugin that the doc belongs to. |
示例配置:
module.exports = {
themeConfig: {
navbar: {
items: [
{
type: 'doc',
position: 'left',
docId: 'introduction',
label: '文档',
},
],
},
},
};
导航栏文档侧边栏链接
你可以将一个导航栏项目链接到某个给定侧边栏的第一个文档链接(可能是文档或者生成类别索引),而不需要硬编码一个文档 ID。
接受的字段:
Name | Type | Default | Description |
---|---|---|---|
type | 'docSidebar' | Required | Sets the type of this navbar item to a sidebar's first document. |
sidebarId | string | Required | The ID of the sidebar that this item is linked to. |
label | string | First document link's sidebar label | The name to be shown for this item. |
position | 'left' | 'right' | 'left' | The side of the navbar this item should appear on. |
docsPluginId | string | 'default' | The ID of the docs plugin that the sidebar belongs to. |
如果你的侧边栏经常更新而且顺序不稳定,请使用这个导航栏项目类型。
示例配置:
module.exports = {
themeConfig: {
navbar: {
items: [
{
type: 'docSidebar',
position: 'left',
sidebarId: 'api',
label: 'API',
},
],
},
},
};
module.exports = {
tutorial: [
{
type: 'autogenerated',
dirName: 'guides',
},
],
api: [
'cli', // 导航栏项会链接到这篇文档
'docusaurus-core',
{
type: 'autogenerated',
dirName: 'api',
},
],
};
导航栏文档版本下拉菜单
如果你使用文档版本化,这个特别的导航栏项目类型会渲染一个下拉菜单,包含你的网站的所有可用版本。
用户可以从一个版本切换到另一个版本。 而仍然保持在同一篇文档上(只要文档 ID 在版本之间保持不变)。
接受的字段:
Name | Type | Default | Description |
---|---|---|---|
type | 'docsVersionDropdown' | Required | Sets the type of this item to a docs version dropdown. |
position | 'left' | 'right' | 'left' | The side of the navbar this item should appear on. |
dropdownItemsBefore | LinkLikeItem[] | [] | Add additional dropdown items at the beginning of the dropdown. |
dropdownItemsAfter | LinkLikeItem[] | [] | Add additional dropdown items at the end of the dropdown. |
docsPluginId | string | 'default' | The ID of the docs plugin that the doc versioning belongs to. |
dropdownActiveClassDisabled | boolean | false | Do not add the link active class when browsing docs. |
示例配置:
module.exports = {
themeConfig: {
navbar: {
items: [
{
type: 'docsVersionDropdown',
position: 'left',
dropdownItemsAfter: [{to: '/versions', label: '所有版本'}],
dropdownActiveClassDisabled: true,
},
],
},
},
};
导航栏文档版本
如果你使用文档版本化,这个特别的的导航栏项目类型会链接到你的文档的活跃版本(正浏览的版本;取决于当前的 URL)。如果没有版本处于活跃状态,则链接到最新版本。
接受的字段:
Name | Type | Default | Description |
---|---|---|---|
type | 'docsVersion' | Required | Sets the type of this item to a doc version link. |
label | string | The active/latest version label. | The name to be shown for this item. |
to | string | The active/latest version. | The internal link that this item points to. |
position | 'left' | 'right' | 'left' | The side of the navbar this item should appear on. |
docsPluginId | string | 'default' | The ID of the docs plugin that the doc versioning belongs to. |
示例配置:
module.exports = {
themeConfig: {
navbar: {
items: [
{
type: 'docsVersion',
position: 'left',
to: '/path',
label: '标签',
},
],
},
},
};
导航栏语言下拉菜单
如果你使用 i18n 功能,这个特别的的导航栏项目类型会渲染一个下拉菜单,包含了你的网站上所有可用的语言。
用户能够从一种语言切换到另一种语言,同时保持在同一个页面上。
接受的字段:
Name | Type | Default | Description |
---|---|---|---|
type | 'localeDropdown' | Required | Sets the type of this item to a locale dropdown. |
position | 'left' | 'right' | 'left' | The side of the navbar this item should appear on. |
dropdownItemsBefore | LinkLikeItem[] | [] | Add additional dropdown items at the beginning of the dropdown. |
dropdownItemsAfter | LinkLikeItem[] | [] | Add additional dropdown items at the end of the dropdown. |
示例配置:
module.exports = {
themeConfig: {
navbar: {
items: [
{
type: 'localeDropdown',
position: 'left',
dropdownItemsAfter: [
{
to: 'https://my-site.com/help-us-translate',
label: '帮助我们翻译',
},
],
},
],
},
},
};
导航栏搜索框
如果你使用搜索功能,搜索框会默认是导航栏中最右边的元素。
然而,通过这个特别的导航栏项目类型,你可以更改默认位置。
Name | Type | Default | Description |
---|---|---|---|
type | 'search' | Required | Sets the type of this item to a search bar. |
position | 'left' | 'right' | 'left' | The side of the navbar this item should appear on. |
className | string | / | Custom CSS class for this navbar item. |
module.exports = {
themeConfig: {
navbar: {
items: [
{
type: 'search',
position: 'right',
},
],
},
},
};
导航栏自定义 HTML 项目
你也可以用这个导航栏项目类型在导航栏中渲染自己的 HTML 标记。
Name | Type | Default | Description |
---|---|---|---|
type | 'html' | Required | Sets the type of this item to a HTML element. |
position | 'left' | 'right' | 'left' | The side of the navbar this item should appear on. |
className | string | '' | Custom CSS class for this navbar item. |
value | string | '' | Custom HTML to be rendered inside this navbar item. |
module.exports = {
themeConfig: {
navbar: {
items: [
{
type: 'html',
position: 'right',
value: '<button>提交反馈</button>',
},
],
},
},
};
自动隐藏顶部导航栏
你可以启用这个很酷的界面功能,它会在用户开始向下滚动页面时,自动隐藏导航栏,当用户向上滚动时再显示它。
module.exports = {
themeConfig: {
navbar: {
hideOnScroll: true,
},
},
};
导航栏样式
你可以把导航栏样式设置为静态,而不禁用主题切换能力。 无论用户选择哪个主题,所选的样式都会被应用。
目前有两种样式选项:dark
和 primary
(基于 --ifm-color-main
的颜色)。 你可以在 Infima 文档中看到样式的预览。
module.exports = {
themeConfig: {
navbar: {
style: 'primary',
},
},
};
代码块
Docusaurus 使用 Prism React Renderer 高亮代码块。 所有配置都在 prism
对象中。
接受的字段:
Name | Type | Default | Description |
---|---|---|---|
theme | PrismTheme | palenight | The Prism theme to use for light-theme code blocks. |
darkTheme | PrismTheme | palenight | The Prism theme to use for dark-theme code blocks. |
defaultLanguage | string | undefined | The side of the navbar this item should appear on. |
magicComments | MagicCommentConfig[] | see below | The list of magic comments. |
type MagicCommentConfig = {
className: string;
line?: string;
block?: {start: string; end: string};
};
const defaultMagicComments = [
{
className: 'theme-code-block-highlighted-line',
line: 'highlight-next-line',
block: {start: 'highlight-start', end: 'highlight-end'},
},
];
主题
默认情况下,我们使用 Palenight 作为语法高亮主题。 你可以从这个可用主题列表中选择一个自定义主题。 你也可以在网站处于暗黑模式时,使用不同的语法高亮主题。
示例配置:
module.exports = {
themeConfig: {
prism: {
theme: require('prism-react-renderer/themes/github'),
darkTheme: require('prism-react-renderer/themes/dracula'),
},
},
};
如果你使用了 Markdown 的行高亮语法,你可能需要为暗黑模式的语法高亮主题指定不同的行高亮背景颜色。 具体教程请参考文档。
默认语言
你可以设置代码块的默认语言。如果代码块开头的三个反引号(就是 ```)后没有添加语言,会使用默认语言。 注意必须传递合法的语言名。
示例配置:
module.exports = {
themeConfig: {
prism: {
defaultLanguage: 'javascript',
},
},
};
页脚
你可以通过 themeConfig.foot
为页脚添加图标和版权声明。 图标可以放在静态文件夹中。 图标 URL 的工作方式和导航栏图标相同。
接受的字段:
Name | Type | Default | Description |
---|---|---|---|
logo | Logo | undefined | Customization of the logo object. See Navbar logo for details. |
copyright | string | undefined | The copyright message to be displayed at the bottom. |
style | 'dark' | 'light' | 'light' | The color theme of the footer component. |
links | (Column | FooterLink)[] | [] | The link groups to be present. |
示例配置:
module.exports = {
themeConfig: {
footer: {
logo: {
alt: 'Facebook 开源图标',
src: 'img/oss_logo.png',
href: 'https://opensource.facebook.com',
width: 160,
height: 51,
},
copyright: `版权所有 © ${new Date().getFullYear()} 我的项目. 使用 Docusaurus 构建.`,
},
},
};
页脚链接
你可以通过 themeConfig.footer.links
为页脚添加链接。 页脚配置有两种类型:多列页脚和简单页脚。
多列页脚链接的每一列都有一个 title
和一个 FooterItem
的列表。
Name | Type | Default | Description |
---|---|---|---|
title | string | undefined | Label of the section of these links. |
items | FooterItem[] | [] | Links in this section. |
每个 FooterItem
接受的字段为:
Name | Type | Default | Description |
---|---|---|---|
label | string | Required | Text to be displayed for this link. |
to | string | Required | Client-side routing, used for navigating within the website. 会自动在开头添加 base URL。 |
href | string | Required | A full-page navigation, used for navigating outside of the website. Only one of to or href should be used. |
html | string | undefined | Renders the html pass-through instead of a simple link. In case html is used, no other options should be provided. |
多列页脚配置示例:
module.exports = {
footer: {
links: [
{
title: '文档',
items: [
{
label: '风格指南',
to: 'docs/',
},
{
label: '第二份文档',
to: 'docs/doc2/',
},
],
},
{
title: '社区',
items: [
{
label: 'Stack Overflow',
href: 'https://stackoverflow.com/questions/tagged/docusaurus',
},
{
label: 'Discord',
href: 'https://discordapp.com/invite/docusaurus',
},
{
label: 'Twitter',
href: 'https://twitter.com/docusaurus',
},
{
html: `
<a href="https://www.netlify.com" target="_blank" rel="noreferrer noopener" aria-label="由 Netlify 部署">
<img src="https://www.netlify.com/img/global/badges/netlify-color-accent.svg" alt="由 Netlify 部署" width="114" height="51" />
</a>
`,
},
],
},
],
},
};
简单页脚就只会显示一行 FooterItem
列表。
简单页脚配置示例:
module.exports = {
footer: {
links: [
{
label: 'Stack Overflow',
href: 'https://stackoverflow.com/questions/tagged/docusaurus',
},
{
label: 'Discord',
href: 'https://discordapp.com/invite/docusaurus',
},
{
label: 'Twitter',
href: 'https://twitter.com/docusaurus',
},
{
html: `
<a href="https://www.netlify.com" target="_blank" rel="noreferrer noopener" aria-label="由Netlify 部署">
<img src="https://www.netlify.com/img/global/badges/netlify-color-accent.svg" alt="由 Netlify 部署" width="114" height="51" />
</a>
`,
},
],
},
};
目录
你可以通过 themeConfig.tableOfContents
调整默认的目录样式。
Name | Type | Default | Description |
---|---|---|---|
minHeadingLevel | number | 2 | The minimum heading level shown in the table of contents. 必须介于 2 到 6 之间,并且小于等于最大值。 |
maxHeadingLevel | number | 3 | Max heading level displayed in the TOC. 必须是 2 到 6 之间的整数。 |
示例配置:
module.exports = {
themeConfig: {
tableOfContents: {
minHeadingLevel: 2,
maxHeadingLevel: 5,
},
},
};
钩子函数
useColorMode
一个用于访问色彩模式 context 的 React 钩子。 这个 context 包含了用于设置浅色/深色模式的函数,以及一个布尔属性,表明现在使用的是哪个模式。
示例用法:
import React from 'react';
import {useColorMode} from '@docusaurus/theme-common';
const Example = () => {
const {colorMode, setColorMode} = useColorMode();
return <h1>暗黑模式现在为{colorMode === 'dark' ? '开启状态': '关闭状态'}</h1>;
};
调用 useColormode
的组件必须是 Layout
的子组件。
function ExamplePage() {
return (
<Layout>
<Example />
</Layout>
);
}
i18n
请先阅读 i18n 简介。
翻译文件位置
- 基础路径:
website/i18n/[语言]/docusaurus-theme-[主题名]
- 多实例路径:N/A
- JSON 文件:由
docusaurus write-translations
提取 - Markdown 文件:N/A
文件系统结构示例
website/i18n/[语言]/docusaurus-theme-classic
│
│ # 主题翻译
├── navbar.json
└── footer.json