跳到主要内容

配置主题

此配置适用于所有 main themes

常用配置

日间模式 - 夜间模式

classic 主题默认提供了对日间模式和夜间模式的支持,并在导航条上提供了切换开关。

可以通过 colorMode 对象进行设置。

Accepted fields:

NameTypeDefaultDescription
defaultMode'light' | 'dark''light'The color mode when user first visits the site.
disableSwitchbooleanfalseHides the switch in the navbar. Useful if you want to support a single color mode.
respectPrefersColorSchemebooleanfalseWhether to use the prefers-color-scheme media-query, using user system preferences, instead of the hardcoded defaultMode.

示例配置:

docusaurus.config.js
module.exports = {
themeConfig: {
colorMode: {
defaultMode: 'light',
disableSwitch: false,
respectPrefersColorScheme: false,
},
},
};
caution

如果开启 respectPrefersColorScheme: true,则 defaultMode 会被用户系统的偏好设置所覆盖。

如果你只想支持某一单一模式,则可能要忽略用户系统的首选项。

Meta image

你可以配置用于 meta 标签的默认图片,尤其是 og:imagetwitter:image

Accepted fields:

NameTypeDefaultDescription
imagestringundefinedThe meta image URL for the site. Relative to your site's "static" directory. Cannot be SVGs. Can be external URLs too.

Example configuration:

docusaurus.config.js
module.exports = {
themeConfig: {
image: 'img/docusaurus.png',
},
};

元数据(Metadata)

你可以配置额外的 HTML 元数据(并覆盖已有的元数据)。

Accepted fields:

NameTypeDefaultDescription
metadataMetadata[][]Any field will be directly passed to the <meta /> tag. Possible fields include id, name, property, content, itemprop, etc.

Example configuration:

docusaurus.config.js
module.exports = {
themeConfig: {
metadata: [{name: 'twitter:card', content: 'summary'}],
},
};

公告条

Sometimes you want to announce something in your website. Just for such a case, you can add an announcement bar. This is a non-fixed and optionally dismissible panel above the navbar. All configuration are in the announcementBar object.

Accepted fields:

NameTypeDefaultDescription
idstring'announcement-bar'Any value that will identify this message.
contentstring''The text content of the announcement. HTML will be interpolated.
backgroundColorstring'#fff'Background color of the entire bar.
textColorstring'#000'Announcement text color.
isCloseablebooleantrueWhether this announcement can be dismissed with a '×' button.

Example configuration:

docusaurus.config.js
module.exports = {
themeConfig: {
announcementBar: {
id: 'support_us',
content:
'We are looking to revamp our docs, please fill <a target="_blank" rel="noopener noreferrer" href="#">this survey</a>',
backgroundColor: '#fafbfc',
textColor: '#091E42',
isCloseable: false,
},
},
};

Accepted fields:

NameTypeDefaultDescription

The logo can be placed in static folder. Logo URL is set to base URL of your site by default. Although you can specify your own URL for the logo, if it is an external link, it will open in a new tab. In addition, you can override a value for the target attribute of logo link, it can come in handy if you are hosting docs website in a subdirectory of your main website, and in which case you probably do not need a link in the logo to the main website will open in a new tab.

To improve dark mode support, you can also set a different logo for this mode.

Accepted fields:

NameTypeDefaultDescription

Example configuration:

docusaurus.config.js
module.exports = {
themeConfig: {
navbar: {
title: 'Site 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 为导航条添加不同的元素。

docusaurus.config.js
module.exports = {
themeConfig: {
navbar: {
items: [
{
type: 'doc',
position: 'left',
docId: 'introduction',
label: 'Docs',
},
{to: 'blog', label: 'Blog', 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 repository',
},
],
},
},
};

The items can have different behaviors based on the type field. The sections below will introduce you to all the types of navbar items available.

By default, Navbar items are regular links (internal or external).

React Router should automatically apply active link styling to links, but you can use activeBasePath in edge cases. For cases in which a link should be active on several different paths (such as when you have multiple doc folders under the same sidebar), you can use activeBaseRegex. activeBaseRegex is a more flexible alternative to activeBasePath and takes precedence over it -- Docusaurus parses it into a regular expression that is tested against the current URL.

出站(外部)链接将被自动添加 target="_blank" rel="noopener noreferrer" 属性。

Accepted fields:

NameTypeDefaultDescription
note

In addition to the fields above, you can specify other arbitrary attributes that can be applied to a HTML link.

Example configuration:

docusaurus.config.js
module.exports = {
themeConfig: {
navbar: {
items: [
{
to: 'docs/introduction',
// Only one of "to" or "href" should be used
// href: 'https://www.facebook.com',
label: 'Introduction',
// Only one of "label" or "html" should be used
// html: '<b>Introduction</b>'
position: 'left',
activeBaseRegex: 'docs/(next|v8)',
target: '_blank',
},
],
},
},
};

Navbar items of the type dropdown has the additional items field, an inner array of navbar items.

Navbar dropdown items only accept the following "link-like" item types:

Note that the dropdown base item is a clickable link as well, so this item can receive any of the props of a plain navbar link.

Accepted fields:

NameTypeDefaultDescription

Example configuration:

docusaurus.config.js
module.exports = {
themeConfig: {
navbar: {
items: [
{
type: 'dropdown',
label: 'Community',
position: 'left',
items: [
{
label: 'Facebook',
href: 'https://www.facebook.com',
},
{
type: 'doc',
label: 'Social',
docId: 'social',
},
// ... more items
],
},
],
},
},
};

如果要链接到某个特定的文档,则这种特殊的导航条元素将根据你所提供的 docId 链接到相应的文档。当浏览具有相同侧边栏的文档时,该链接将被赋予 navbar__link--active 类。

Accepted fields:

NameTypeDefaultDescription

Example configuration:

docusaurus.config.js
module.exports = {
themeConfig: {
navbar: {
items: [
{
type: 'doc',
position: 'left',
docId: 'introduction',
label: 'Docs',
},
],
},
},
};

You can link a navbar item to the first document link (which can be a doc link or a generated category index) of a given sidebar without having to hardcode a doc ID.

Accepted fields:

NameTypeDefaultDescription
tip

Use this navbar item type if your sidebar is updated often and the order is not stable.

Example configuration:

docusaurus.config.js
module.exports = {
themeConfig: {
navbar: {
items: [
{
type: 'docSidebar',
position: 'left',
sidebarId: 'api',
label: 'API',
},
],
},
},
};
sidebars.js
module.exports = {
tutorial: [
{
type: 'autogenerated',
dirName: 'guides',
},
],
api: [
'cli', // The navbar item will be linking to this doc
'docusaurus-core',
{
type: 'autogenerated',
dirName: 'api',
},
],
};

If you use docs with versioning, this special navbar item type that will render a dropdown with all your site's available versions.

The user will be able to switch from one version to another, while staying on the same doc (as long as the doc id is constant across versions).

Accepted fields:

NameTypeDefaultDescription

Example configuration:

docusaurus.config.js
module.exports = {
themeConfig: {
navbar: {
items: [
{
type: 'docsVersionDropdown',
position: 'left',
dropdownItemsAfter: [{to: '/versions', label: 'All versions'}],
dropdownActiveClassDisabled: true,
},
],
},
},
};

If you use docs with versioning, this special navbar item type will link to the active/browsed version of your doc (depends on the current URL), and fallback to the latest version.

Accepted fields:

NameTypeDefaultDescription

Example configuration:

docusaurus.config.js
module.exports = {
themeConfig: {
navbar: {
items: [
{
type: 'docsVersion',
position: 'left',
to: '/path',
label: 'label',
},
],
},
},
};

If you use the i18n feature, this special navbar item type will render a dropdown with all your site's available locales.

The user will be able to switch from one locale to another, while staying on the same page.

Accepted fields:

NameTypeDefaultDescription

Example configuration:

docusaurus.config.js
module.exports = {
themeConfig: {
navbar: {
items: [
{
type: 'localeDropdown',
position: 'left',
dropdownItemsAfter: [
{
to: 'https://my-site.com/help-us-translate',
label: 'Help us translate',
},
],
},
],
},
},
};

如果你使用了 搜索功能,则搜索框将放置于导航条的最右侧。

不过,对于这一特殊的导航条元素,你可以更改它的默认位置。

NameTypeDefaultDescription
docusaurus.config.js
module.exports = {
themeConfig: {
navbar: {
items: [
{
type: 'search',
position: 'right',
},
],
},
},
};

You can also render your own HTML markup inside a navbar item using this navbar item type.

NameTypeDefaultDescription
docusaurus.config.js
module.exports = {
themeConfig: {
navbar: {
items: [
{
type: 'html',
position: 'right',
value: '<button>Give feedback</button>',
},
],
},
},
};

自动隐藏的粘性(sticky)导航条

你可以开启这个酷炫的 UI 功能,当用户开始向下滚动页面时自动隐藏导航条,当用户向上滚动页面时则显示导航条。

docusaurus.config.js
module.exports = {
themeConfig: {
navbar: {
hideOnScroll: true,
},
},
};

You can set the static Navbar style without disabling the theme switching ability. The selected style will always apply no matter which theme user have selected.

当前,有两种可用的样式:darkprimary (基于 --ifm-color-primary 颜色)。你可以在 Infima 文档 中查看样式的预览效果。

docusaurus.config.js
module.exports = {
themeConfig: {
navbar: {
style: 'primary',
},
},
};

CodeBlock

Docusaurus uses Prism React Renderer to highlight code blocks. All configuration are in the prism object.

Accepted fields:

NameTypeDefaultDescription
themePrismThemepalenightThe Prism theme to use for light-theme code blocks.
darkThemePrismThemepalenightThe Prism theme to use for dark-theme code blocks.
defaultLanguagestringundefinedThe side of the navbar this item should appear on.
magicCommentsMagicCommentConfig[]see belowThe 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 作为语法高亮的主题。你可以从 可用的主题列表 中指定一个。如果网站处于夜间模式时,你还可以指定一个不同的语法高亮主题使用。

示例配置:

docusaurus.config.js
module.exports = {
themeConfig: {
prism: {
theme: require('prism-react-renderer/themes/github'),
darkTheme: require('prism-react-renderer/themes/dracula'),
},
},
};
note

如果你使用了代码行高亮的 Markdown 语法,则可能需要为夜间模式的语法高亮主题指定一个不同的背景色。请参阅 该指导文档

默认编程语言

如果在三个起始反引号(例如 ```)之后未标示本代码块所使用的编程语言,则该代码块将被视为配置文件中设置的默认编程语言。请注意,编程语言名称 必须是表中所列出的,例如:

示例配置:

docusaurus.config.js
module.exports = {
themeConfig: {
prism: {
defaultLanguage: 'javascript',
},
},
};

你可以通过 themeConfig.footer 向页脚添加 logo 和版权声明。logo 可以放置于 static 目录 中。此处的 logo 所对应的 URL 与导航条上的 logo 所对应的 URL 的工作方式一致。

Accepted fields:

NameTypeDefaultDescription

Example configuration:

docusaurus.config.js
module.exports = {
themeConfig: {
footer: {
logo: {
alt: 'Facebook Open Source Logo',
src: 'img/oss_logo.png',
href: 'https://opensource.facebook.com',
width: 160,
height: 51,
},
copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`,
},
},
};

You can add links to the footer via themeConfig.footer.links. There are two types of footer configurations: multi-column footers and simple footers.

Multi-column footer links have a title and a list of FooterItems for each column.

NameTypeDefaultDescription

Accepted fields of each FooterItem:

NameTypeDefaultDescription

Example multi-column configuration:

docusaurus.config.js
module.exports = {
footer: {
links: [
{
title: 'Docs',
items: [
{
label: 'Style Guide',
to: 'docs/',
},
{
label: 'Second Doc',
to: 'docs/doc2/',
},
],
},
{
title: 'Community',
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="Deploys by Netlify">
<img src="https://www.netlify.com/img/global/badges/netlify-color-accent.svg" alt="Deploys by Netlify" width="114" height="51" />
</a>
`,
},
],
},
],
},
};

A simple footer just has a list of FooterItems displayed in a row.

Example simple configuration:

docusaurus.config.js
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="Deploys by Netlify">
<img src="https://www.netlify.com/img/global/badges/netlify-color-accent.svg" alt="Deploys by Netlify" width="114" height="51" />
</a>
`,
},
],
},
};

Table of Contents

You can adjust the default table of contents via themeConfig.tableOfContents.

NameTypeDefaultDescription
minHeadingLevelnumber2The minimum heading level shown in the table of contents. Must be between 2 and 6 and lower or equal to the max value.
maxHeadingLevelnumber3Max heading level displayed in the TOC. Should be an integer between 2 and 6.

Example configuration:

docusaurus.config.js
module.exports = {
themeConfig: {
tableOfContents: {
minHeadingLevel: 2,
maxHeadingLevel: 5,
},
},
};

Hooks

useColorMode

A React hook to access the color context. This context contains functions for setting light and dark mode and exposes boolean variable, indicating which mode is currently in use.

Usage example:

import React from 'react';
import {useColorMode} from '@docusaurus/theme-common';

const Example = () => {
const {colorMode, setColorMode} = useColorMode();

return <h1>Dark mode is now {colorMode === 'dark' ? 'on' : 'off'}</h1>;
};
note

The component calling useColorMode must be a child of the Layout component.

function ExamplePage() {
return (
<Layout>
<Example />
</Layout>
);
}

i18n

Read the i18n introduction first.

Translation files location

  • Base path: website/i18n/[locale]/docusaurus-theme-[themeName]
  • Multi-instance path: N/A
  • JSON files: extracted with docusaurus write-translations
  • Markdown files: N/A

Example file-system structure

website/i18n/[locale]/docusaurus-theme-classic

# translations for the theme
├── navbar.json
└── footer.json