版本：3.8.1

主题配置

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

通用

颜色模式

经典主题默认提供明暗模式支持，并为用户提供导航栏切换功能。

可以在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。相对于您站点的“static”目录。不能是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:
        '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,
    },
  },
};

插件

我们的主主题为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`	logo对象的自定义。
`items`	`NavbarItem[]`	`[]`	导航栏项目列表。参见下文规范。
`hideOnScroll`	`boolean`	`false`	用户向下滚动时是否隐藏导航栏。
`style`	`'primary' \| 'dark'`	与主题相同	设置导航栏样式，忽略明暗主题。

Logo可以放置在静态文件夹中。Logo URL默认设置为您站点的基础URL。虽然您可以为logo指定自己的URL，但如果它是外部链接，它将在新标签页中打开。此外，您可以覆盖logo链接的target属性值，如果您将文档网站托管在主网站的子目录中，这将非常有用，在这种情况下，您可能不需要logo中的链接在新标签页中打开主网站。

为了改善暗模式支持，您还可以为此模式设置不同的logo。

接受的字段

名称	类型	默认值	描述
`alt`	`string`	`undefined`	logo图像的Alt标签。
`src`	`string`	必需	logo图像的URL。基础URL默认会被附加。
`srcDark`	`string`	`logo.src`	在暗模式下使用的替代图像URL。
`href`	`string`	`siteConfig.baseUrl`	点击logo时导航到的链接。
`width`	`string \| number`	`undefined`	指定`width`属性。
`height`	`string \| number`	`undefined`	指定`height`属性。
`target`	`string`	根据`href`计算（外部链接将在新标签页中打开，其他链接在当前标签页中打开）。	链接的`target`属性；控制链接是在新标签页、当前标签页还是其他方式打开。
`className`	`string`	`undefined`	应用于图像的CSS类。
`style`	`对象`	`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.org.cn/',
        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应自动将活动链接样式应用于链接，但在边缘情况下您可以使用activeBasePath。对于链接应在多个不同路径上处于活动状态的情况（例如，当您在同一侧边栏下有多个文档文件夹时），您可以使用activeBaseRegex。activeBaseRegex是activeBasePath更灵活的替代方案，并优先于它——Docusaurus将其解析为与当前URL进行测试的正则表达式。

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

接受的字段

名称	类型	默认值	描述
`type`	`'default'`	可选	将此项目的类型设置为链接。
`label`	`string`	必需	此项目显示的名称。
`html`	`string`	可选	与`label`相同，但渲染纯HTML而不是文本内容。
`to`	`string`	必需	客户端路由，用于在网站内部导航。baseUrl将自动添加到此值的前面。
`href`	`string`	必需	整页导航，用于在网站外部导航。只能使用`to`或`href`中的一个。
`prependBaseUrlToHref`	`boolean`	`false`	将baseUrl添加到`href`值的前面。
`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://#',
          label: 'Introduction',
          // Only one of "label" or "html" should be used
          // html: '<b>Introduction</b>'
          position: 'left',
          activeBaseRegex: 'docs/(next|v8)',
          target: '_blank',
        },
      ],
    },
  },
};

类型为dropdown的导航栏项目具有额外的items字段，这是一个导航栏项目的内部数组。

导航栏下拉菜单项目只接受以下“链接类”项目类型

导航栏链接
导航栏文档链接
导航栏文档版本
导航栏文档侧边栏
带有自定义HTML的导航栏

请注意，下拉菜单的基础项目也是一个可点击的链接，因此此项目可以接收普通导航栏链接的任何属性。

接受的字段

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

示例配置

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'dropdown',
          label: 'Community',
          position: 'left',
          items: [
            {
              label: 'Facebook',
              href: 'https://#',
            },
            {
              type: 'doc',
              label: 'Social',
              docId: 'social',
            },
            // ... more items
          ],
        },
      ],
    },
  },
};

如果您想链接到特定文档，这种特殊的导航栏项目类型将渲染指向所提供docId文档的链接。只要您浏览同一侧边栏的文档，它就会获得navbar__link--active类。

接受的字段

名称	类型	默认值	描述
`type`	`'doc'`	必需	将此项目的类型设置为文档链接。
`docId`	`string`	必需	此项目链接到的文档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'`	必需	将此导航栏项目的类型设置为侧边栏的第一个文档。
`sidebarId`	`string`	必需	此项目链接到的侧边栏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'`	必需	将此项目的类型设置为文档版本下拉菜单。
`position`	`'left' \| 'right'`	`'left'`	此项目应出现在导航栏的哪一侧。
`dropdownItemsBefore`	`LinkLikeItem[]`	`[]`	在下拉菜单的开头添加额外的下拉项目。
`dropdownItemsAfter`	`LinkLikeItem[]`	`[]`	在下拉菜单的末尾添加额外的下拉项目。
`docsPluginId`	`string`	`'default'`	文档版本控制所属的文档插件ID。
`dropdownActiveClassDisabled`	`boolean`	`false`	浏览文档时不要添加链接活动类。
`versions`	`DropdownVersions`	`undefined`	指定要在下拉菜单中包含的自定义版本列表。详细信息请参阅版本控制指南。

类型

type DropdownVersion = {
  /** Allows you to provide a custom display label for each version. */
  label?: string;
};

type DropdownVersions = string[] | {[versionName: string]: DropdownVersion};

示例配置

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

如果您使用带版本控制的文档，这种特殊的导航栏项目类型将链接到您的文档的活动/浏览版本（取决于当前URL），并回退到最新版本。

接受的字段

名称	类型	默认值	描述
`type`	`'docsVersion'`	必需	将此项目的类型设置为文档版本链接。
`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',
        },
      ],
    },
  },
};

如果您使用国际化功能，这种特殊的导航栏项目类型将渲染一个下拉菜单，其中包含您网站所有可用的区域设置。

用户可以在不同区域设置之间切换，同时停留在同一页面上。

接受的字段

名称	类型	默认值	描述
`type`	`'localeDropdown'`	必需	将此项目的类型设置为区域设置下拉菜单。
`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',
            },
          ],
        },
      ],
    },
  },
};

如果您使用搜索功能，搜索栏将是导航栏中最右侧的元素。

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

名称	类型	默认值	描述
`type`	`'search'`	必需	将此项目的类型设置为搜索栏。
`position`	`'left' \| 'right'`	`'left'`	此项目应出现在导航栏的哪一侧。
`className`	`string`	/	此导航栏项目的自定义CSS类。

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

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

名称	类型	默认值	描述
`type`	`'html'`	必需	将此项目的类型设置为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>',
        },
      ],
    },
  },
};

您可以启用这个酷炫的UI功能，当用户开始向下滚动页面时自动隐藏导航栏，当用户向上滚动时再次显示。

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

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

目前，有两种可能的样式选项：dark和primary（基于--ifm-color-primary颜色）。您可以在Infima文档中查看样式预览。

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

代码块

Docusaurus使用Prism React Renderer来高亮代码块。所有配置都在prism对象中。

接受的字段

名称	类型	默认值	描述
`theme`	`PrismTheme`	`palenight`	用于亮色主题代码块的Prism主题。
`darkTheme`	`PrismTheme`	`palenight`	用于暗色主题代码块的Prism主题。
`defaultLanguage`	`string`	`undefined`	用于未声明任何明确语言的代码块的默认语言。
`magicComments`	`MagicCommentConfig[]`	见下文	魔术注释列表。

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

主题

默认情况下，我们使用Palenight作为语法高亮主题。您可以从可用主题列表中指定自定义主题。当网站处于暗模式时，您也可以使用不同的语法高亮主题。

示例配置

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

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

注意

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

默认语言

如果代码块开头的三重反引号后没有添加任何语言（即```），您可以为代码块设置默认语言。请注意，必须传入有效的语言名称。

示例配置

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

您可以通过themeConfig.footer向页脚添加logo和版权信息。Logo可以放置在静态文件夹中。Logo URL的工作方式与导航栏logo相同。

接受的字段

名称	类型	默认值	描述
`logo`	`Logo`	`undefined`	logo对象的自定义。有关详细信息，请参见导航栏Logo。
`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.`,
    },
  },
};

您可以通过themeConfig.footer.links向页脚添加链接。页脚配置有两种类型：多列页脚和简单页脚。

多列页脚链接每列都有一个title和FooterItem列表。

名称	类型	默认值	描述
`title`	`string`	`undefined`	这些链接部分的标签。
`items`	`FooterItem[]`	`[]`	此部分中的链接。

每个FooterItem接受的字段

名称	类型	默认值	描述
`label`	`string`	必需	此链接要显示的文本。
`to`	`string`	必需	客户端路由，用于在网站内部导航。baseUrl将自动添加到此值的前面。
`href`	`string`	必需	整页导航，用于在网站外部导航。只能使用`to`或`href`中的一个。
`html`	`string`	`undefined`	渲染HTML直通内容，而非简单链接。如果使用`html`，则不应提供其他选项。

多列配置示例

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

一个简单的页脚只包含一排显示的FooterItem列表。

简单配置示例

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

名称	类型	默认值	描述
`minHeadingLevel`	`number`	`2`	目录中显示的最小标题级别。必须介于 2 和 6 之间，且小于或等于最大值。
`maxHeadingLevel`	`number`	`3`	目录中显示的最大标题级别。应为2到6之间的整数。

Hook

`useColorMode`

一个用于访问颜色上下文的React Hook。此上下文包含用于选择亮色/暗色/系统模式的函数，并公开当前颜色模式和用户选择。颜色模式值不应用于动态内容渲染（见下文）。

使用示例

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

属性

colorMode: 'light' | 'dark'：当前应用于UI的有效颜色模式。它不能是null。
colorModeChoice: 'light' | 'dark' | null：用户明确选择的颜色模式。如果用户尚未做出任何选择，或者他们将选择重置为系统/默认值，则可以为null。
setColorMode(colorModeChoice: 'light' | 'dark' | null, options: {persist: boolean}): void：当用户明确选择颜色模式时调用的函数。null允许将选择重置为系统/默认值。默认情况下，该选择会持久化在localStorage中并在页面重新加载时恢复，但您可以使用{persist: false}选择退出。

警告

在渲染React组件时，请勿使用colorMode和colorModeChoice。这样做很可能导致FOUC（无样式内容闪烁）、布局偏移和React 水合不匹配，如果您使用它们动态渲染JSX内容。

然而，这些值在React水合后是安全的，可以在useEffect和事件监听器中使用，就像上面的MyColorModeButton示例一样。

如果您需要根据当前主题动态渲染内容，避免FOUC、布局偏移和水合不匹配的唯一方法是依赖CSS选择器来动态渲染内容，基于我们在页面显示任何内容之前设置的html数据属性。

<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']

为什么在渲染时colorMode和colorModeChoice不安全？

要理解这个问题，您需要了解React 水合的工作原理。

在静态站点生成阶段，Docusaurus不知道用户选择的颜色模式是什么，并且useColorMode()返回以下静态值

colorMode = themeConfig.colorMode.defaultMode
colorModeChoice = null

在第一次React客户端渲染（水合）期间，React必须生成完全相同的HTML标记，并且也将使用这些静态值。

正确的colorMode和colorModeChoice值只会在第二次React渲染中提供。

通常，以下组件将导致React水合不匹配。在React水合时，标签可能会从light切换到dark，从而导致令人困惑的用户体验。

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

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

注意

调用useColorMode的组件必须是Layout组件的子组件。

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

i18n

请先阅读 i18n 简介。

翻译文件位置

基础路径：website/i18n/[locale]/docusaurus-theme-[themeName]
多实例路径：不适用
JSON 文件：使用 docusaurus write-translations 提取
Markdown文件：不适用

文件系统结构示例

website/i18n/[locale]/docusaurus-theme-classic
│
│ # translations for the theme
├── navbar.json
└── footer.json

主题配置

通用

颜色模式

元图像

元数据

公告栏

插件

文档

博客

导航栏

导航栏Logo

导航栏项目

导航栏链接

导航栏文档链接

导航栏链接到侧边栏

导航栏文档版本

导航栏搜索

带自定义HTML的导航栏

自动隐藏粘性导航栏

导航栏样式

代码块

主题

默认语言

页脚

页脚链接

目录

Hook

`useColorMode`

i18n

翻译文件位置

文件系统结构示例

通用​

颜色模式​

元图像​

元数据​

公告栏​

插件​

文档​

博客​

导航栏​

导航栏Logo​

导航栏项目​

导航栏链接​

导航栏下拉菜单​

导航栏文档链接​

导航栏链接到侧边栏​

导航栏文档版本下拉菜单​

导航栏文档版本​

导航栏区域设置下拉菜单​

导航栏搜索​

带自定义HTML的导航栏​

自动隐藏粘性导航栏​

导航栏样式​

代码块​

主题​

默认语言​

页脚​

页脚链接​

目录​

Hook​

useColorMode​

i18n​

翻译文件位置​

文件系统结构示例​

通用

颜色模式

元图像

元数据

公告栏

插件

文档

博客

导航栏

导航栏Logo

导航栏项目

导航栏链接

导航栏下拉菜单

导航栏文档链接

导航栏链接到侧边栏

导航栏文档版本下拉菜单

导航栏文档版本

导航栏区域设置下拉菜单

导航栏搜索

带自定义HTML的导航栏

自动隐藏粘性导航栏

导航栏样式

代码块

主题

默认语言

页脚

页脚链接

目录

Hook

`useColorMode`

i18n

翻译文件位置

文件系统结构示例