版本：3.4.0

主题配置

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

警告

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

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

Meta image

你可以配置用于元标签的默认图像，尤其是 og:image 和 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'},
      },
    },
  },
};

你可以通过 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',
        },
      ],
    },
  },
};

根据 type 字段，导航栏项目的行为可能不同。下面的部分会为你介绍所有的导航栏项目类型。

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

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`	如果有需要，可以替代 activeBasePath。
`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`	要附加到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`	未显式声明任何语言的情况下，用于代码块的默认语言。
`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`	要在底部显示的版权消息，也支持自定义 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: 'X',
            href: 'https://x.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: 'X',
        href: 'https://x.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 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 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 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