版本：3.2.1

主题配置

This configuration applies to all main themes.

Common

Color mode

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

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

接受的字段：

参数	类型	默认值	描述
`defaultMode`	`'light' \| 'dark'`	`'light'`	用户首次访问网站时的色彩模式。
`disableSwitch`	`boolean`	`false`	在导航栏隐藏按钮。如果你想要只支持一种色彩模式很有用。
`respectPrefersColorScheme`	`boolean`	`false`	Whether to use the `prefers-color-scheme` media-query, using user system preferences, instead of the hardcoded `defaultMode`.

示例配置：

docusaurus.config.js
export default {
  themeConfig: {
    colorMode: {
      defaultMode: 'light',
      disableSwitch: false,
      respectPrefersColorScheme: false,
    },
  },
};

warning

With respectPrefersColorScheme: true, the defaultMode is overridden by user system preferences.

如果你只想支持一种色彩模式，你大概率会想要忽略用户系统的偏好设置。

Meta image

You can configure a default image that will be used for your meta tag, in particular og:image and twitter:image.

接受的字段：

参数	类型	默认值	描述
`image`	`string`	`undefined`	网站的元数据图像 URL。相对于你的网站的静态目录。不能是 SVG。可以是外部链接。

示例配置：

docusaurus.config.js
export default {
  themeConfig: {
    image: 'img/docusaurus.png',
  },
};

Metadata

你可以配置额外的 HTML 元数据（以及覆盖现有数据）。

接受的字段：

参数	类型	默认值	描述
`metadata`	`Metadata[]`	`[]`	Any field will be directly passed to the `<meta />` tag. Possible fields include `id`, `name`, `property`, `content`, `itemprop`, etc.

示例配置：

docusaurus.config.js
export default {
  themeConfig: {
    metadata: [{name: 'twitter:card', content: 'summary'}],
  },
};

Announcement bar

有时候，你需要在网站上发布告示。这种情况下，你可以添加一个告示条。这是位于导航栏上方的一个面板，非固定而且可以关闭。 All configuration are in the announcementBar object.

接受的字段：

参数	类型	默认值	描述
`id`	`string`	`'announcement-bar'`	任何能够唯一标识此信息的值。
`content`	`string`	`''`	告示的文字内容。 HTML 也可以识别。
`backgroundColor`	`string`	`'#fff'`	告示条的背景颜色。
`textColor`	`string`	`'#000'`	告示的文字颜色。
`isCloseable`	`boolean`	`true`	是否可以用 '×' 按钮关闭告示。

示例配置：

docusaurus.config.js
export default {
  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,
    },
  },
};

接受的字段：

参数	类型	默认值	描述
`title`	`string`	`undefined`	导航栏标题。
`logo`	See below	`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`	Required	图片的 URL。 Base URL 会被默认添加。
`srcDark`	`string`	`logo.src`	暗黑模式下使用的替代图像 URL。
`href`	`string`	`siteConfig.baseUrl`	点击图标时跳转到的链接。
`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.
`className`	`string`	`undefined`	图片的 CSS 类名。
`style`	`object`	`undefined`	内联 CSS 样式对象。 React/JSX 风格，所有属性都是驼峰格式 (camelCase)。

示例配置：

docusaurus.config.js
export default {
  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,
        className: 'custom-navbar-logo-class',
        style: {border: 'solid red'},
      },
    },
  },
};

You can add items to the navbar via themeConfig.navbar.items.

docusaurus.config.js
export default {
  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. 下面的部分会为你介绍所有的导航栏项目类型。

导航栏项目默认是一个普通链接（内部或外部均可）。

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.

Outbound (external) links automatically get target="_blank" rel="noopener noreferrer" attributes.

接受的字段：

参数	类型	默认值	描述
`type`	`'default'`	可选	把这个项目的类型设置为链接。
`label`	`string`	Required	项目显示的名称。
`html`	`string`	可选	Same as `label`, but renders pure HTML instead of text content.
`to`	`string`	Required	客户端路由，用于站内导航。会自动在开头添加 base URL。
`href`	`string`	Required	整页导航，用于站外跳转。 Only one of `to` or `href` should be used.
`prependBaseUrlToHref`	`boolean`	`false`	Prepends the baseUrl to `href` values.
`position`	`'left' \| 'right'`	`'left'`	项目应该出现在导航栏的哪一侧。
`activeBasePath`	`string`	`to` / `href`	在以此路径开始的所有路由上应用活跃类样式。通常没有必要设置。
`activeBaseRegex`	`string`	`undefined`	Alternative to `activeBasePath` if required.
`className`	`string`	`''`	自定义 CSS 类（用于任何项目的样式）。

备注

除了上面的字段外，你可以指定其他任何 HTML 链接接受的属性。

示例配置：

docusaurus.config.js
export default {
  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:

Navbar link
Navbar doc link
Navbar docs version
Navbar doc sidebar
Navbar with custom HTML

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.

接受的字段：

参数	类型	默认值	描述
`type`	`'dropdown'`	可选	把这个项目的类型设置为下拉菜单。
`label`	`string`	Required	项目显示的名称。
`items`	`LinkLikeItem[]`	Required	下拉菜单中包含的项目。
`position`	`'left' \| 'right'`	`'left'`	项目应该出现在导航栏的哪一侧。

示例配置：

docusaurus.config.js
export default {
  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
          ],
        },
      ],
    },
  },
};

If you want to link to a specific doc, this special navbar item type will render the link to the doc of the provided docId. It will get the class navbar__link--active as long as you browse a doc of the same sidebar.

接受的字段：

参数	类型	默认值	描述
`type`	`'doc'`	Required	把这个项目的类型设置为文档链接。
`docId`	`string`	Required	这个项目链接到的文档的 ID。
`label`	`string`	`docId`	项目显示的名称。
`position`	`'left' \| 'right'`	`'left'`	项目应该出现在导航栏的哪一侧。
`docsPluginId`	`string`	`'default'`	这篇文档所属的文档插件的 ID。

示例配置：

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

你可以将一个导航栏项目链接到某个给定侧边栏的第一个文档链接（可能是文档或者生成类别索引），而不需要硬编码一个文档 ID。

接受的字段：

参数	类型	默认值	描述
`type`	`'docSidebar'`	Required	把这个项目的类型设置为侧边栏链接。
`sidebarId`	`string`	Required	这个项目链接到的侧边栏的 ID。
`label`	`string`	第一个文档链接的侧边栏标签	项目显示的名称。
`position`	`'left' \| 'right'`	`'left'`	项目应该出现在导航栏的哪一侧。
`docsPluginId`	`string`	`'default'`	这个侧边栏所属的文档插件的 ID。

提示

如果你的侧边栏经常更新而且顺序不稳定，请使用这个导航栏项目类型。

示例配置：

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'docSidebar',
          position: 'left',
          sidebarId: 'api',
          label: 'API',
        },
      ],
    },
  },
};

sidebars.js
export default {
  tutorial: [
    {
      type: 'autogenerated',
      dirName: 'guides',
    },
  ],
  api: [
    'cli', // The navbar item will be linking to this doc
    'docusaurus-core',
    {
      type: 'autogenerated',
      dirName: 'api',
    },
  ],
};

如果你使用文档版本化，这个特别的导航栏项目类型会渲染一个下拉菜单，包含你的网站的所有可用版本。

用户可以从一个版本切换到另一个版本。而仍然保持在同一篇文档上（只要文档 ID 在版本之间保持不变）。

接受的字段：

参数	类型	默认值	描述
`type`	`'docsVersionDropdown'`	Required	把这个项目的类型设置为文档版本下拉菜单。
`position`	`'left' \| 'right'`	`'left'`	项目应该出现在导航栏的哪一侧。
`dropdownItemsBefore`	`LinkLikeItem[]`	`[]`	在下拉菜单开头添加额外的项目。
`dropdownItemsAfter`	`LinkLikeItem[]`	`[]`	在下拉菜单结尾添加额外的项目。
`docsPluginId`	`string`	`'default'`	这个版本下拉菜单所属的文档插件的 ID。
`dropdownActiveClassDisabled`	`boolean`	`false`	不要在浏览文档时添加链接活跃类名。

示例配置：

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

如果你使用文档版本化，这个特别的的导航栏项目类型会链接到你的文档的活跃版本（正浏览的版本；取决于当前的 URL）。如果没有版本处于活跃状态，则链接到最新版本。

接受的字段：

参数	类型	默认值	描述
`type`	`'docsVersion'`	Required	把这个项目的类型设置为文档版本链接。
`label`	`string`	活跃/最新版本的标签。	项目显示的名称。
`to`	`string`	活跃/最新版本。	项目指向的内部链接。
`position`	`'left' \| 'right'`	`'left'`	项目应该出现在导航栏的哪一侧。
`docsPluginId`	`string`	`'default'`	这个版本下拉菜单所属的文档插件的 ID。

示例配置：

docusaurus.config.js
export default {
  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.

用户能够从一种语言切换到另一种语言，同时保持在同一个页面上。

接受的字段：

参数	类型	默认值	描述
`type`	`'localeDropdown'`	Required	把这个项目的类型设置为语言下拉菜单。
`position`	`'left' \| 'right'`	`'left'`	项目应该出现在导航栏的哪一侧。
`dropdownItemsBefore`	`LinkLikeItem[]`	`[]`	在下拉菜单开头添加额外的项目。
`dropdownItemsAfter`	`LinkLikeItem[]`	`[]`	在下拉菜单结尾添加额外的项目。
`queryString`	`string`	`undefined`	The query string to be appended to the URL.

示例配置：

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

If you use the search, the search bar will be the rightmost element in the navbar.

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

参数	类型	默认值	描述
`type`	`'search'`	Required	把这个项目的类型设置为搜索框。
`position`	`'left' \| 'right'`	`'left'`	项目应该出现在导航栏的哪一侧。
`className`	`string`	/	项目的自定义 CSS 类名。

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'search',
          position: 'right',
        },
      ],
    },
  },
};

你也可以用这个导航栏项目类型在导航栏中渲染自己的 HTML 标记。

参数	类型	默认值	描述
`type`	`'html'`	Required	把这个项目的类型设置为 HTML 元素。
`position`	`'left' \| 'right'`	`'left'`	项目应该出现在导航栏的哪一侧。
`className`	`string`	`''`	项目的自定义 CSS 类名。
`value`	`string`	`''`	在这个项目中渲染的自定义 HTML。

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

你可以启用这个很酷的界面功能，它会在用户开始向下滚动页面时，自动隐藏导航栏，当用户向上滚动时再显示它。

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      hideOnScroll: true,
    },
  },
};

你可以把导航栏样式设置为静态，而不禁用主题切换能力。无论用户选择哪个主题，所选的样式都会被应用。

Currently, there are two possible style options: dark and primary (based on the --ifm-color-primary color). You can see the styles preview in the Infima documentation.

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      style: 'primary',
    },
  },
};

CodeBlock

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

接受的字段：

参数	类型	默认值	描述
`theme`	`PrismTheme`	`palenight`	用于浅色模式下代码块的 Prism 主题。
`darkTheme`	`PrismTheme`	`palenight`	用于暗黑模式下代码块的 Prism 主题。
`defaultLanguage`	`string`	`undefined`	The default language to use for code blocks not declaring any explicit language.
`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'},
  },
];

Theme

By default, we use Palenight as syntax highlighting theme. You can specify a custom theme from the list of available themes. 你也可以在网站处于暗黑模式时，使用不同的语法高亮主题。

示例配置：

docusaurus.config.js
import {themes as prismThemes} from 'prism-react-renderer';

export default {
  themeConfig: {
    prism: {
      theme: prismThemes.github,
      darkTheme: prismThemes.dracula,
    },
  },
};

备注

如果你使用了 Markdown 的行高亮语法，你可能需要为暗黑模式的语法高亮主题指定不同的行高亮背景颜色。 Refer to the docs for guidance.

Default language

你可以设置代码块的默认语言。如果代码块开头的三个反引号（就是 ```）后没有添加语言，会使用默认语言。 Note that a valid language name must be passed.

示例配置：

docusaurus.config.js
export default {
  themeConfig: {
    prism: {
      defaultLanguage: 'javascript',
    },
  },
};

You can add logo and a copyright to the footer via themeConfig.footer. Logo can be placed in static folder. 图标 URL 的工作方式和导航栏图标相同。

接受的字段：

参数	类型	默认值	描述
`logo`	`Logo`	`undefined`	图标对象的自定义。 See Navbar logo for details.
`copyright`	`string`	`undefined`	The copyright message to be displayed at the bottom, also supports custom HTML.
`style`	`'dark' \| 'light'`	`'light'`	页脚组件的色彩主题。
`links`	`(Column \| FooterLink)[]`	`[]`	要显示的链接组。

示例配置：

docusaurus.config.js
export default {
  themeConfig: {
    footer: {
      logo: {
        alt: 'Meta Open Source Logo',
        src: 'img/meta_oss_logo.png',
        href: 'https://opensource.fb.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.

参数	类型	默认值	描述
`title`	`string`	`undefined`	这些链接所在部分的标签。
`items`	`FooterItem[]`	`[]`	这一部分的链接。

Accepted fields of each FooterItem:

参数	类型	默认值	描述
`label`	`string`	Required	链接显示的文字。
`to`	`string`	Required	客户端路由，用于站内导航。会自动在开头添加 base URL。
`href`	`string`	Required	整页导航，用于站外跳转。 Only one of `to` or `href` should be used.
`html`	`string`	`undefined`	渲染纯 HTML 而不是普通链接。 In case `html` is used, no other options should be provided.

多列页脚配置示例：

docusaurus.config.js
export default {
  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.

简单页脚配置示例：

docusaurus.config.js
export default {
  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>
          `,
      },
    ],
  },
};

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

参数	类型	默认值	描述
`minHeadingLevel`	`number`	`2`	目录中显示的最小标题层级。必须介于 2 到 6 之间，并且小于等于最大值。
`maxHeadingLevel`	`number`	`3`	目录显示的最大标题层级。必须是 2 到 6 之间的整数。

示例配置：

docusaurus.config.js
export default {
  themeConfig: {
    tableOfContents: {
      minHeadingLevel: 2,
      maxHeadingLevel: 5,
    },
  },
};

Hooks

`useColorMode`

一个用于访问色彩模式 context 的 React 钩子。这个 context 包含了用于设置浅色/深色模式的函数，以及一个布尔属性，表明现在使用的是哪个模式。

示例用法：

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

备注

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/[语言]/docusaurus-theme-classic
│
│ # 主题翻译
├── navbar.json
└── footer.json

主题配置

Common

Color mode

Meta image

Metadata

Announcement bar

Navbar

Navbar logo

Navbar items

Navbar link

Navbar doc link

Navbar linked to a sidebar

Navbar docs version

Navbar search

Navbar with custom HTML

Auto-hide sticky navbar

Navbar style

CodeBlock

Theme

Default language

Footer

Footer Links

Table of Contents

Hooks

`useColorMode`

i18n

Translation files location

Example file-system structure

主题配置

Common​

Color mode​

Meta image​

Metadata​

Announcement bar​

Navbar​

Navbar logo​

Navbar items​

Navbar link​

Navbar dropdown​

Navbar doc link​

Navbar linked to a sidebar​

Navbar docs version dropdown​

Navbar docs version​

Navbar locale dropdown​

Navbar search​

Navbar with custom HTML​

Auto-hide sticky navbar​

Navbar style​

CodeBlock​

Theme​

Default language​

Footer​

Footer Links​

Table of Contents​

Hooks​

useColorMode​

i18n​

Translation files location​

Example file-system structure​

Common

Color mode

Meta image

Metadata

Announcement bar

Navbar

Navbar logo

Navbar items

Navbar link

Navbar dropdown

Navbar doc link

Navbar linked to a sidebar

Navbar docs version dropdown

Navbar docs version

Navbar locale dropdown

Navbar search

Navbar with custom HTML

Auto-hide sticky navbar

Navbar style

CodeBlock

Theme

Default language

Footer

Footer Links

Table of Contents

Hooks

`useColorMode`

i18n

Translation files location

Example file-system structure