跳转至主内容
Version: 2.0.0-beta.8

主题配置

此配置适用于所有的主要主题

通用

Color mode

经典主题提供默认的白色主题和暗色主题,用户可通过导航栏切换。

It is possible to customize the color mode support within the colorMode object.

Accepted fields:

NameTypeDefaultDescription
defaultMode!!crwdBlockTags_263_sgaTkcolBdwrc!!'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.
switchConfigSee belowSee belowDark/light switch icon options.
switchConfig.darkIconstring'🌜'Icon for the switch while in dark mode.
switchConfig.darkIconStyleJSX style object (see documentation){}CSS to apply to dark icon.
switchConfig.lightIconstring'🌞'Icon for the switch while in light mode.
switchConfig.lightIconStyleJSX style object{}CSS to apply to light icon.

Example configuration:

docusaurus.config.js
module.exports = {
themeConfig: {
colorMode: {
defaultMode: 'light',
disableSwitch: false,
respectPrefersColorScheme: false,
switchConfig: {
darkIcon: '🌙',
darkIconStyle: {
marginLeft: '2px',
},
// Unicode icons such as '\u2600' will work
// Unicode with 5 chars require brackets: '\u{1F602}'
lightIcon: '\u{1F602}',
lightIconStyle: {
marginLeft: '1px',
},
},
},
},
};
caution

若使用 respectPrefersColorScheme: truedefaultMode 将被用户系统的偏好设置覆盖。

若您只想支持单一颜色模式,您应该想忽略用户系统的偏好设置。

元数据标签

您可以配置用于元标签的默认图像,尤其是 og:imagetwitter:image

Accepted fields:

NameTypeDefaultDescription
imagestringundefinedThe meta image URL for the site. Relative to your site's "static" directory. Cannot be SVGs. 可为外部链接。

Example configuration:

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

元数据

您可配置额外的 HTML 元数据(并覆盖现有数据)。

Accepted fields:

NameTypeDefaultDescription
metadatasMetadata[][]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: {
metadatas: [{name: 'twitter:card', content: 'summary'}],
},
};

公告栏

有时候,您需要在网站上公布内容。 这种情况下,您可以添加一个公告栏。 这是位于导航栏上方的一个不固定且可忽略的面板。 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
titlestringundefinedTitle for the navbar.
logoSee belowundefinedCustomization of the logo object.
itemsNavbarItem[][]A list of navbar items. See specification below.
hideOnScrollbooleanfalseWhether the navbar is hidden when the user scrolls down.
style!!crwdBlockTags_307_sgaTkcolBdwrc!!Same as themeSets the navbar style, ignoring the dark/light theme.

The logo can be placed in static folder. 标签URL将被默认设置位你网站的基本URL 尽管你可以指定自己的URL作为标签,但如果他有外部链接,他将会打开一个新页。 此外,您可以覆盖徽标链接的目标属性值, 如果您正在主网站的子目录中托管文档网站,它可以马上到来。 在这种情况下,您可能不需要在主网站的徽标上链接,将在一个新标签中打开.

为了改善黑暗模式的支持,您也可以为此模式设置一个不同的徽标。

Accepted fields:

NameTypeDefaultDescription
altstringundefinedAlt tag for the logo image.
srcstringRequiredURL to the logo image. Base URL is appended by default.
srcDarkstringlogo.srcAn alternative image URL to use in dark mode.
hrefstringsiteConfig.baseUrlLink to navigate to when the logo is clicked.
targetstringCalculated 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.

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',
},
},
},
};

你可以通过 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.

默认情况下,导航栏项目是常规链接 (内部或外部) 。

React Router 应该自动应用激活链接样式到链接,但你可以在边缘情况下使用 ActiveBasePath。 对于链接应该在几个不同路径上激活的情况(例如你在同一个侧边栏下有多个操作文件夹的情况), 您可以使用 activeBaseRegexActiveBaseRegex 是一个 ActiveBasePath 的更灵活的替代品,并且优先于它 -- Docusaurus 解析它为一个正则表达式,并用当前的 URL 测试。

出站(外部) 链接自动获得 target="_blank" rel="noopener noreferrer" 属性。

Accepted fields:

NameTypeDefaultDescription
labelstringRequiredThe name to be shown for this item.
tostringRequiredClient-side routing, used for navigating within the website. The baseUrl will be automatically prepended to this value.
hrefstringRequiredA full-page navigation, used for navigating outside of the website. Only one of to or href should be used.
prependBaseUrlToHrefbooleanfalsePrepends the baseUrl to href values.
position!!crwdBlockTags_350_sgaTkcolBdwrc!!'left'The side of the navbar this item should appear on.
activeBasePathstringto / hrefTo apply the active class styling on all routes starting with this path. This usually isn't necessary.
activeBaseRegexstringundefinedAlternative to activeBasePath if required.
classNamestring''Custom CSS class (for styling any item).
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',
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
labelstringRequiredThe name to be shown for this item.
items!!crwdBlockTags_357_sgaTkcolBdwrc!!RequiredThe items to be contained in the dropdown.
position!!crwdBlockTags_358_sgaTkcolBdwrc!!'left'The side of the navbar this item should appear on.

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
docIdstringRequiredThe ID of the doc that this item links to.
labelstringdocIdThe name to be shown for this item.
position!!crwdBlockTags_370_sgaTkcolBdwrc!!'left'The side of the navbar this item should appear on.
docsPluginIdstring'default'The ID of the docs plugin that the doc belongs to.

Example configuration:

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

如果你使用带有版本的文档,这个特殊的导航栏项目类型将会呈现你所有站点可用的版本的下拉。

用户可以从一个版本切换到另一个版本。 当保持在同一文档上(只要文档id是跨版本不变)。

Accepted fields:

NameTypeDefaultDescription
position!!crwdBlockTags_384_sgaTkcolBdwrc!!'left'The side of the navbar this item should appear on.
dropdownItemsBefore!!crwdBlockTags_385_sgaTkcolBdwrc!![]Add additional dropdown items at the beginning of the dropdown.
dropdownItemsAfter!!crwdBlockTags_386_sgaTkcolBdwrc!![]Add additional dropdown items at the end of the dropdown.
docsPluginIdstring'default'The ID of the docs plugin that the doc versioning belongs to.
dropdownActiveClassDisabledbooleanfalseDo not add the link active class when browsing docs.

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
labelstringThe active/latest version label.The name to be shown for this item.
tostringThe active/latest version.The internal link that this item points to.
position!!crwdBlockTags_397_sgaTkcolBdwrc!!'left'The side of the navbar this item should appear on.
docsPluginIdstring'default'The ID of the docs plugin that the doc versioning belongs to.

Example configuration:

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

如果你使用 i18n feature, 这种特殊的导航栏项目类型将显示一个包含您网站所有可用语言环境的下拉菜单。

用户将能够在同一页面上从一个区域切换到另一个区域。

Accepted fields:

NameTypeDefaultDescription
position!!crwdBlockTags_405_sgaTkcolBdwrc!!'left'The side of the navbar this item should appear on.
dropdownItemsBefore!!crwdBlockTags_406_sgaTkcolBdwrc!![]Add additional dropdown items at the beginning of the dropdown.
dropdownItemsAfter!!crwdBlockTags_407_sgaTkcolBdwrc!![]Add additional dropdown items at the end of the dropdown.

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',
},
],
},
],
},
},
};

如果您使用 search,搜索栏将是导航栏中最右边的元素。

然而,通过这个特殊的导航栏项目类型,您可以更改默认位置。

NameTypeDefaultDescription
position!!crwdBlockTags_411_sgaTkcolBdwrc!!'left'The side of the navbar this item should appear on.
docusaurus.config.js
module.exports = {
themeConfig: {
navbar: {
items: [
{
type: 'search',
position: 'right',
},
],
},
},
};

自动隐藏置顶导航栏

当用户开始滚动页面时,您可以启用这个自动隐藏导航栏的很酷的界面功能, 当用户滚动时再显示它。

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

您可以设置静态导航栏样式而不禁用主题切换能力。 无论用户选择哪个主题,所选样式都将始终适用。

当前有两个可能的样式选项: darkprimary (基于 --ifm-color-main 颜色)。 您可以在 Infima 文档 中看到样式预览。

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

代码块

Docusaurus使用 Prism React Renderer 高亮代码块。 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.

主题

默认情况下,我们使用 Palenight 作为语法高亮主题。 您可以从 个可用主题列表 指定一个自定义主题。 You may also use a different syntax highlighting theme when the site is in dark mode.

Example configuration:

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

如果您使用的是高亮Markdown 语法,您可能需要为暗模式语法高亮主题指定不同的高亮背景颜色。 参考 文档以获取指南

默认语言

如果在开头的三次背面后没有添加语言,你可以设置代码块的默认语言(例如```)。 Note that a valid language name must be passed.

Example configuration:

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

您可以通过 themeConfig.foot 将标志和版权添加到页脚。 标志可以放置在 静态文件夹 中。 徽标URL的工作方式与导航栏徽标相同。

Accepted fields:

NameTypeDefaultDescription
logoLogoundefinedCustomization of the logo object. See Navbar logo for details.
copyrightstringundefinedThe copyright message to be displayed at the bottom.
style!!crwdBlockTags_434_sgaTkcolBdwrc!!'light'The color theme of the footer component.
itemsFooterItem[][]The link groups to be present.

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',
},
copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`,
},
},
};

You can add links to the footer via themeConfig.footer.links.

Accepted fields of each link section:

NameTypeDefaultDescription
titlestringundefinedLabel of the section of these links.
itemsFooterLink[][]Links in this section.

Accepted fields of each item in items:

NameTypeDefaultDescription
labelstringRequiredText to be displayed for this link.
tostringRequiredClient-side routing, used for navigating within the website. The baseUrl will be automatically prepended to this value.
hrefstringRequiredA full-page navigation, used for navigating outside of the website. Only one of to or href should be used.
htmlstringundefinedRenders the html pass-through instead of a simple link. In case html is used, no other options should be provided.

Example 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" />
</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,
},
},
};

钩子函数

使用主题文本

执行hook接收主题内容 This context contains functions for setting light and dark mode and exposes boolean variable, indicating which mode is currently in use.

示例用法:

import React from 'react';
//高亮下一行
import useThemeContext from '@theme/hooks/useThemeContext';

const Example = () => {
// 高亮下一行
const {isDarkTheme, setLightTheme, setDarkTheme} = useThemeContext();

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

组件useThemeContext一定是 Layout的子项

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

i18n

请先阅读 i18n 简介

翻译文件位置

  • 基础路径: website/i18n/<locale>/docusaurus-theme-<themeName>
  • 多实例路径: N/A
  • JSON files: extracted with docusaurus write-translations
  • Markdown files: N/A

文件系统结构示例

website/i18n/<locale>/docusaurus-theme-classic

# 主题翻译
├── navbar.json
└── footer.json