Version: 2.0.0-beta.5 🚧

主题配置

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

通用#

Color mode#

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

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

Accepted fields:

Name	Type	Default	Description
`defaultMode`	!!crwdBlockTags_255_sgaTkcolBdwrc!!	`'light'`	The color mode when user first visits the site.
`disableSwitch`	`boolean`	`false`	Hides the switch in the navbar. Useful if you want to support a single color mode.
`respectPrefersColorScheme`	`boolean`	`false`	Whether to use the `prefers-color-scheme` media-query, using user system preferences, instead of the hardcoded `defaultMode`.
`switchConfig`	See below	See below	Dark/light switch icon options.
`switchConfig.darkIcon`	`string`	`'🌜'`	Icon for the switch while in dark mode.
`switchConfig.darkIconStyle`	JSX style object (see documentation)	`{}`	CSS to apply to dark icon.
`switchConfig.lightIcon`	`string`	`'🌞'`	Icon for the switch while in light mode.
`switchConfig.lightIconStyle`	JSX 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: true，defaultMode 将被用户系统的偏好设置覆盖。

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

元数据标签#

您可以配置用于元标签的默认图像，尤其是 og:image 和 twitter:image。

Accepted fields:

Name	Type	Default	Description
`image`	`string`	`undefined`	The 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:

Name	Type	Default	Description
`metadatas`	`Metadata[]`	`[]`	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:

Name	Type	Default	Description
`id`	`string`	`'announcement-bar'`	Any value that will identify this message.
`content`	`string`	`''`	The text content of the announcement. HTML will be interpolated.
`backgroundColor`	`string`	`'#fff'`	Background color of the entire bar.
`textColor`	`string`	`'#000'`	Announcement text color.
`isCloseable`	`boolean`	`true`	Whether 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:

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. See specification below.
`hideOnScroll`	`boolean`	`false`	Whether the navbar is hidden when the user scrolls down.
`style`	!!crwdBlockTags_299_sgaTkcolBdwrc!!	Same as theme	Sets the navbar style, ignoring the dark/light theme.

Navbar logo#

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

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

Accepted fields:

Name	Type	Default	Description
`alt`	`string`	`undefined`	Alt tag for the logo image.
`src`	`string`	Required	URL to the logo image. Base URL is appended by default.
`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.
`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.

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.

Navbar link#

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

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

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

Accepted fields:

Name	Type	Default	Description
`label`	`string`	Required	The name to be shown for this item.
`to`	`string`	Required	Client-side routing, used for navigating within the website. The baseUrl will be automatically prepended to this value.
`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`	!!crwdBlockTags_342_sgaTkcolBdwrc!!	`'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. This usually isn't necessary.
`activeBaseRegex`	`string`	`undefined`	Alternative to `activeBasePath` if required.
`className`	`string`	`''`	Custom CSS class (for styling any item).

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

导航栏下拉列表#

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:

Navbar link
导航栏文档链接
导航栏文档版本

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:

Name	Type	Default	Description
`label`	`string`	Required	The name to be shown for this item.
`items`	!!crwdBlockTags_349_sgaTkcolBdwrc!!	Required	The items to be contained in the dropdown.
`position`	!!crwdBlockTags_350_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:

Name	Type	Default	Description
`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`	!!crwdBlockTags_362_sgaTkcolBdwrc!!	`'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.

Example configuration:

docusaurus.config.js

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

导航栏文档版本下拉列表#

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

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

Accepted fields:

Name	Type	Default	Description
`position`	!!crwdBlockTags_376_sgaTkcolBdwrc!!	`'left'`	The side of the navbar this item should appear on.
`dropdownItemsBefore`	!!crwdBlockTags_377_sgaTkcolBdwrc!!	`[]`	Add additional dropdown items at the beginning of the dropdown.
`dropdownItemsAfter`	!!crwdBlockTags_378_sgaTkcolBdwrc!!	`[]`	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.

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:

Name	Type	Default	Description
`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`	!!crwdBlockTags_389_sgaTkcolBdwrc!!	`'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.

Example configuration:

docusaurus.config.js

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

导航栏区域下拉列表#

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

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

Accepted fields:

Name	Type	Default	Description
`position`	!!crwdBlockTags_397_sgaTkcolBdwrc!!	`'left'`	The side of the navbar this item should appear on.
`dropdownItemsBefore`	!!crwdBlockTags_398_sgaTkcolBdwrc!!	`[]`	Add additional dropdown items at the beginning of the dropdown.
`dropdownItemsAfter`	!!crwdBlockTags_399_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，搜索栏将是导航栏中最右边的元素。

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

Name	Type	Default	Description
`position`	!!crwdBlockTags_403_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,    },  },};

导航栏样式#

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

当前有两个可能的样式选项： dark 和 primary (基于 --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:

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.

主题#

默认情况下，我们使用 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:

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`	!!crwdBlockTags_426_sgaTkcolBdwrc!!	`'light'`	The color theme of the footer component.
`items`	`FooterItem[]`	`[]`	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:

Name	Type	Default	Description
`title`	`string`	`undefined`	Label of the section of these links.
`items`	`FooterLink[]`	`[]`	Links in this section.

Accepted fields of each item in items:

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. The baseUrl will be automatically prepended to this value.
`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.

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

钩子函数#

`使用主题文本`#

执行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

通用#

Color mode#

caution

元数据标签#

元数据#

公告栏#

导航栏#

Navbar logo#

导航栏项目#

Navbar link#

导航栏下拉列表#

导航栏 文档 链接#

导航栏 文档版本下拉列表#

导航栏文档版本#

导航栏区域下拉列表#

导航栏搜索#

自动隐藏置顶导航栏#

导航栏样式#

代码块#

主题#

note

默认语言#

页脚#

页脚链接#

钩子函数#

使用主题文本#

note

i18n#

翻译文件位置#

文件系统结构示例#

导航栏文档链接#

导航栏文档版本下拉列表#

`使用主题文本`#