主题配置

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

通用

颜色模式

经典主题默认提供亮色和暗色模式支持，并在导航栏中为用户提供切换开关。

可以在 colorMode 对象中自定义颜色模式支持。

接受的字段：

名称	类型	默认值	描述
`defaultMode`	`'light' \| 'dark'`	`'light'`	用户首次访问站点时的颜色模式。
`disableSwitch`	`boolean`	`false`	隐藏导航栏中的切换开关。如果您只想支持单一颜色模式，这很有用。
`respectPrefersColorScheme`	`boolean`	`false`	是否使用 `prefers-color-scheme` 媒体查询，使用用户系统偏好，而不是硬编码的 `defaultMode`。

示例配置：

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

注意

使用 respectPrefersColorScheme: true 时，defaultMode 将被用户系统偏好覆盖。

如果您只想支持一种颜色模式，您可能希望忽略用户系统偏好。

元图像

您可以配置一个默认图像，该图像将用于您的元标签，特别是 og:image 和 twitter:image。

接受的字段：

名称	类型	默认值	描述
`image`	`string`	`undefined`	站点的元图像 URL。相对于站点的"静态"目录。不能是 SVG。也可以是外部 URL。

示例配置：

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

元数据

您可以配置其他 HTML 元数据（并覆盖现有的）。

接受的字段：

名称	类型	默认值	描述
`metadata`	`Metadata[]`	`[]`	任何字段都将直接传递给 `<meta />` 标签。可能的字段包括 `id`、`name`、`property`、`content`、`itemprop` 等。

示例配置：

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

公告栏

有时您想在网站上宣布一些内容。为此，您可以添加一个公告栏。这是一个非固定的、可选择关闭的面板，位于导航栏上方。所有配置都在 announcementBar 对象中。

接受的字段：

名称	类型	默认值	描述
`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:
        '我们正在重新设计文档，请填写<a target="_blank" rel="noopener noreferrer" href="#">此调查</a>',
      backgroundColor: '#fafbfc',
      textColor: '#091E42',
      isCloseable: false,
    },
  },
};

插件

我们的主要主题为 Docusaurus 核心内容插件提供了额外的主题配置选项。

文档

名称	类型	默认值	描述
`versionPersistence`	`'localStorage' \| 'none'`	`undefined`	定义首选文档版本的浏览器持久性。
`sidebar.hideable`	`boolean`	`false`	在侧边栏底部显示隐藏按钮。
`sidebar.autoCollapseCategories`	`boolean`	`false`	自动折叠导航到的类别的所有同级类别。

示例配置：

docusaurus.config.js
export default {
  themeConfig: {
    docs: {
      versionPersistence: 'localStorage',
      sidebar: {
        hideable: false,
        autoCollapseCategories: false,
      },
    },
  },
};

博客

名称	类型	默认值	描述
`sidebar.groupByYear`	`boolean`	`true`	按年份对侧边栏博客文章进行分组。

示例配置：

docusaurus.config.js
export default {
  themeConfig: {
    blog: {
      sidebar: {
        groupByYear: true,
      },
    },
  },
};

接受的字段：

名称	类型	默认值	描述
`title`	`string`	`undefined`	导航栏的标题。
`logo`	见下文	`undefined`	徽标对象的自定义。
`items`	`NavbarItem[]`	`[]`	导航栏项目列表。请参见下面的规范。
`hideOnScroll`	`boolean`	`false`	用户向下滚动时是否隐藏导航栏。
`style`	`'primary' \| 'dark'`	与主题相同	设置导航栏样式，忽略深浅主题。

徽标可以放置在静态文件夹中。默认情况下，徽标 URL 设置为站点的基本 URL。尽管您可以为徽标指定自己的 URL，但如果它是外部链接，它将在新标签页中打开。此外，您可以覆盖徽标链接的目标属性的值，如果您的文档网站托管在主网站的子目录中，这可能会很方便，在这种情况下，您可能不需要徽标链接到主网站并在新标签页中打开。

接受的字段：

名称	类型	默认值	描述
`src`	`string`	`undefined`	徽标图像的路径。
`srcDark`	`string`	`undefined`	深色模式下使用的徽标图像的路径。如果未指定，将使用 `src`。
`href`	`string`	站点的基本 URL	徽标链接的目标 URL。
`target`	`string`	`'_self'`	徽标链接的目标属性。
`width`	`string \| number`	`undefined`	徽标的宽度。
`height`	`string \| number`	`undefined`	徽标的高度。
`alt`	`string`	站点标题	徽标的替代文本。

示例配置：

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      logo: {
        alt: 'My Site Logo',
        src: 'img/logo.svg',
        srcDark: 'img/logo-dark.svg',
        href: 'https://docusaurus.io/',
        target: '_self',
        width: 32,
        height: 32,
      },
    },
  },
};

导航栏项目可以是以下类型：

default：常规链接
dropdown：带有子项目的下拉菜单
docsVersion：文档版本选择器
localeDropdown：语言环境选择器

默认项目

名称	类型	默认值	描述
`type`	`'default'`	`undefined`	项目类型。
`label`	`string`	`undefined`	项目的标签文本。
`to`	`string`	`undefined`	链接的目标路径。
`href`	`string`	`undefined`	外部链接的完整 URL。
`prependBaseUrlToHref`	`boolean`	`false`	是否将基本 URL 添加到 `href`。
`position`	`'left' \| 'right'`	`'left'`	项目在导航栏中的位置。
`activeBasePath`	`string`	`undefined`	用于确定项目是否处于活动状态的基本路径。
`activeBaseRegex`	`string`	`undefined`	用于确定项目是否处于活动状态的正则表达式。
`className`	`string`	`undefined`	要应用于项目的 CSS 类。

示例配置：

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'default',
          label: 'Docs',
          to: '/docs/intro',
          position: 'left',
        },
        {
          type: 'default',
          label: 'Blog',
          to: '/blog',
          position: 'left',
        },
        {
          type: 'default',
          label: 'GitHub',
          href: 'https://github.com/facebook/docusaurus',
          position: 'right',
        },
      ],
    },
  },
};

名称	类型	默认值	描述
`type`	`'dropdown'`	`undefined`	项目类型。
`label`	`string`	`undefined`	下拉菜单的标签文本。
`items`	`NavbarItem[]`	`[]`	下拉菜单中的子项目。
`position`	`'left' \| 'right'`	`'left'`	项目在导航栏中的位置。

示例配置：

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'dropdown',
          label: 'Versions',
          position: 'right',
          items: [
            {
              label: 'v2.0.0-beta.0',
              to: '/versions',
            },
            {
              label: 'v1.0.0',
              to: '/versions-1-0-0',
            },
          ],
        },
      ],
    },
  },
};

文档版本选择器

名称	类型	默认值	描述
`type`	`'docsVersion'`	`undefined`	项目类型。
`label`	`string`	当前版本	版本选择器的标签文本。
`position`	`'left' \| 'right'`	`'left'`	项目在导航栏中的位置。

示例配置：

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

名称	类型	默认值	描述
`type`	`'localeDropdown'`	`undefined`	项目类型。
`position`	`'left' \| 'right'`	`'left'`	项目在导航栏中的位置。
`queryString`	`string`	`undefined`	更改语言环境时要附加到 URL 的查询参数。

示例配置：

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'localeDropdown',
          position: 'right',
          queryString: '?persistLocale=true',
        },
      ],
    },
  },
};

您可以自定义站点的页脚。

接受的字段：

名称	类型	默认值	描述
`style`	`'dark' \| 'light'`	与主题相同	页脚的样式，忽略深浅主题。
`logo`	见下文	`undefined`	页脚徽标的自定义。
`copyright`	`string`	`undefined`	版权声明文本。
`links`	`FooterLink[]`	`[]`	页脚链接列表。

名称	类型	默认值	描述
`src`	`string`	`undefined`	徽标图像的路径。
`srcDark`	`string`	`undefined`	深色模式下使用的徽标图像的路径。如果未指定，将使用 `src`。
`href`	`string`	`undefined`	徽标链接的目标 URL。
`width`	`string \| number`	`undefined`	徽标的宽度。
`height`	`string \| number`	`undefined`	徽标的高度。
`alt`	`string`	站点标题	徽标的替代文本。

名称	类型	默认值	描述
`title`	`string`	`undefined`	链接组的标题。
`items`	`FooterLinkItem[]`	`[]`	链接组中的链接项目。

名称	类型	默认值	描述
`label`	`string`	`undefined`	链接的标签文本。
`to`	`string`	`undefined`	内部链接的目标路径。
`href`	`string`	`undefined`	外部链接的完整 URL。
`prependBaseUrlToHref`	`boolean`	`false`	是否将基本 URL 添加到 `href`。
`target`	`string`	`undefined`	链接的目标属性。

示例配置：

docusaurus.config.js
export default {
  themeConfig: {
    footer: {
      style: 'dark',
      logo: {
        alt: 'My Site Logo',
        src: 'img/logo.svg',
        href: 'https://docusaurus.io/',
        width: 32,
        height: 32,
      },
      copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`,
      links: [
        {
          title: 'Docs',
          items: [
            {
              label: 'Tutorial',
              to: '/docs/intro',
            },
          ],
        },
        {
          title: 'Community',
          items: [
            {
              label: 'Stack Overflow',
              href: 'https://stackoverflow.com/questions/tagged/docusaurus',
            },
          ],
        },
      ],
    },
  },
};

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

Name	Type	Default	Description
`minHeadingLevel`	`number`	`2`	The minimum heading level shown in the table of contents. Must be between 2 and 6 and lower or equal to the max value.
`maxHeadingLevel`	`number`	`3`	Max heading level displayed in the TOC. Should be an integer between 2 and 6.

Example configuration:

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

Hooks

`useColorMode`

A React hook to access the color context. This context contains functions for selecting light/dark/system mode and exposes the current color mode and the choice from the user. The color mode values should not be used for dynamic content rendering (see below).

Usage example:

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

const MyColorModeButton = () => {
  const {
    colorMode, // the "effective" color mode, never null
    colorModeChoice, // the color mode chosen by the user, can be null
    setColorMode, // set the color mode chosen by the user
  } = useColorMode();

  return (
    <button
      onClick={() => {
        const nextColorMode = colorModeChoice === 'dark' ? 'light' : 'dark';
        setColorMode(nextColorMode);
      }}>
      Toggle color mode
    </button>
  );
};

Attributes:

colorMode: 'light' | 'dark': The effective color mode currently applied to the UI. It cannot be null.
colorModeChoice: 'light' | 'dark' | null: The color mode explicitly chosen by the user. It can be null if user has not made any choice yet, or if they reset their choice to the system/default value.
setColorMode(colorModeChoice: 'light' | 'dark' | null, options: {persist: boolean}): void: A function to call when the user explicitly chose a color mode. null permits to reset the choice to the system/default value. By default, the choice is persisted in localStorage and restored on page reload, but you can opt out with {persist: false}.

注意

Don't use colorMode and colorModeChoice while rendering React components. Doing so is likely to produce FOUC, layout shifts and React hydration mismatches if you use them to render JSX content dynamically.

However, these values are safe to use after React hydration, in useEffect and event listeners, like in the MyColorModeButton example above.

If you need to render content dynamically depending on the current theme, the only way to avoid FOUC, layout shifts and hydration mismatch is to rely on CSS selectors to render content dynamically, based on the html data attributes that we set before the page displays anything:

<html data-theme="<light | dark>" data-theme-choice="<light | dark | system>">
  <!-- content -->
</html>

[data-theme='light']
[data-theme='dark']

[data-theme-choice='light']
[data-theme-choice='dark']
[data-theme-choice='system']

Why are colorMode and colorModeChoice unsafe when rendering?

To understand the problem, you need to understand how React hydration works.

During the static site generation phase, Docusaurus doesn't know what the user color mode choice is, and useColorMode() returns the following static values:

colorMode = themeConfig.colorMode.defaultMode
colorModeChoice = null

During the very first React client-side render (the hydration), React must produce the exact same HTML markup, and will also use these static values.

The correct colorMode and colorModeChoice values will only be provided in the second React render.

Typically, the following component will lead to React hydration mismatches. The label may switch from light to dark while React hydrates, leading to a confusing user experience.

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

const DisplayCurrentColorMode = () => {
  const {colorMode} = useColorMode();
  return <span>{colorMode}</span>;
};

备注

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

主题配置

通用

颜色模式

元图像

元数据

公告栏

插件

文档

博客

导航栏

导航栏徽标

Navbar items

默认项目

文档版本选择器

页脚

页脚徽标

页脚链接

页脚链接项目

Table of Contents

Hooks

`useColorMode`

i18n

Translation files location

Example file-system structure

通用​

颜色模式​

元图像​

元数据​

公告栏​

插件​

文档​

博客​

导航栏​

导航栏徽标​

Navbar items​

默认项目​

下拉项目​

文档版本选择器​

语言环境选择器​

页脚​

页脚徽标​

页脚链接​

页脚链接项目​

Table of Contents​

Hooks​

useColorMode​

i18n​

Translation files location​

Example file-system structure​

通用

颜色模式

元图像

元数据

公告栏

插件

文档

博客

导航栏

导航栏徽标

Navbar items

默认项目

下拉项目

文档版本选择器

语言环境选择器

页脚

页脚徽标

页脚链接

页脚链接项目

Table of Contents

Hooks

`useColorMode`

i18n

Translation files location

Example file-system structure