主题配置

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

通用配置

颜色模式

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

可以在 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:
        '我们正在寻求改进我们的文档，请填写<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`	Logo 对象的自定义。
`items`	`NavbarItem[]`	`[]`	导航栏项目列表。具体规范见下文。
`hideOnScroll`	`boolean`	`false`	当用户向下滚动时是否隐藏导航栏。
`style`	`'primary' \| 'dark'`	与主题相同	设置导航栏样式，忽略深色/浅色主题。

Logo 可以放置在静态资源文件夹中。Logo 的 URL 默认设置为你网站的根路径。虽然你可以为 Logo 指定自己的 URL，但如果它是一个外部链接，它将在新标签页中打开。此外，你可以为 Logo 链接的 target 属性覆盖一个值，如果你将文档网站托管在主网站的子目录中，这会很有用，这种情况下你可能不希望 Logo 中的链接到主网站的页面在新标签页中打开。

为了改善深色模式的支持，你也可以为此模式设置一个不同的 Logo。

可接受的字段：

名称	类型	默认值	描述
`alt`	`string`	`undefined`	Logo 图片的 alt 标签。
`src`	`string`	必需	Logo 图片的 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`	`object`	`undefined`	CSS 内联样式对象。采用 React/JSX 风格，使用驼峰式属性。

配置示例：

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      title: '网站标题',
      logo: {
        alt: '网站 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: '文档',
        },
        {to: 'blog', label: '博客', 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`	必需	客户端路由，用于在网站内部导航。根路径将自动添加到此值的前面。
`href`	`string`	必需	整页导航，用于导航到网站外部。`to` 或 `href` 只能使用一个。
`prependBaseUrlToHref`	`boolean`	`false`	将根路径添加到 `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',
          // "to" 和 "href" 只能使用一个
          // href: 'https://www.facebook.com',
          label: '简介',
          // "label" 和 "html" 只能使用一个
          // html: '<b>简介</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: '社区',
          position: 'left',
          items: [
            {
              label: 'Facebook',
              href: 'https://www.facebook.com',
            },
            {
              type: 'doc',
              label: '社交',
              docId: 'social',
            },
            // ... 更多项目
          ],
        },
      ],
    },
  },
};

如果你想链接到一个特定的文档，这个特殊的导航栏项目类型将渲染到所提供 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: '文档',
        },
      ],
    },
  },
};

你可以将一个导航栏项目链接到给定侧边栏的第一个文档链接（可以是一个文档链接或一个生成的分类索引），而无需硬编码文档 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', // 导航栏项目将链接到此文档
    '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 = {
  /** 允许你为每个版本提供自定义的显示标签。 */
  label?: string;
};

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

配置示例：

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'docsVersionDropdown',
          position: 'left',
          dropdownItemsAfter: [{to: '/versions', label: '所有版本'}],
          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',
        },
      ],
    },
  },
};

如果你使用国际化（i18n）功能，这个特殊的导航栏项目类型将渲染一个包含你网站所有可用语言环境的下拉菜单。

用户将能够从一个语言环境切换到另一个，同时停留在同一页面上。

可接受的字段：

名称	类型	默认值	描述
`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: '帮助我们翻译',
            },
          ],
        },
      ],
    },
  },
};

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

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

名称	类型	默认值	描述
`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>提供反馈</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 开源 Logo',
        src: 'img/meta_oss_logo.png',
        href: 'https://opensource.fb.com',
        width: 160,
        height: 51,
      },
      copyright: `版权所有 © ${new Date().getFullYear()} My Project, Inc. 使用道格龙（Docusaurus）构建。`,
    },
  },
};

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

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

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

每个 FooterItem 的可接受字段：

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

多列配置示例：

docusaurus.config.js
export default {
  footer: {
    links: [
      {
        title: '文档',
        items: [
          {
            label: '样式指南',
            to: 'docs/',
          },
          {
            label: '第二篇文档',
            to: 'docs/doc2/',
          },
        ],
      },
      {
        title: '社区',
        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="由 Netlify 部署">
                  <img src="https://www.netlify.com/img/global/badges/netlify-color-accent.svg" alt="由 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="由 Netlify 部署">
              <img src="https://www.netlify.com/img/global/badges/netlify-color-accent.svg" alt="由 Netlify 部署" width="114" height="51" />
            </a>
          `,
      },
    ],
  },
};

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

Hooks

`useColorMode`

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

用法示例：

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

const MyColorModeButton = () => {
  const {
    colorMode, // "有效"的颜色模式，永不为 null
    colorModeChoice, // 用户选择的颜色模式，可以为 null
    setColorMode, // 设置用户选择的颜色模式
  } = useColorMode();

  return (
    <button
      onClick={() => {
        const nextColorMode = colorModeChoice === 'dark' ? 'light' : 'dark';
        setColorMode(nextColorMode);
      }}>
      切换颜色模式
    </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>">
  <!-- 内容 -->
</html>

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

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

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

要理解这个问题，你需要了解 React 水合（hydration）是如何工作的。

在静态站点生成阶段，道格龙（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]
多实例路径: N/A
JSON 文件: 使用 docusaurus write-translations 提取
Markdown 文件: N/A

文件系统结构示例

website/i18n/[locale]/docusaurus-theme-classic
│
│ # 主题的翻译
├── navbar.json
└── footer.json

主题配置

通用配置

颜色模式

元图片

元数据

公告栏

插件

文档

博客

导航栏

导航栏 Logo

导航栏项目

导航栏链接

导航栏文档链接

链接到侧边栏的导航栏

导航栏文档版本

导航栏搜索

带自定义 HTML 的导航栏

自动隐藏粘性导航栏

导航栏样式

代码块

主题

默认语言

页脚

页脚链接

目录

Hooks

`useColorMode`

国际化（i18n）

翻译文件位置

文件系统结构示例

通用配置​

颜色模式​

元图片​

元数据​

公告栏​

插件​

文档​

博客​

导航栏​

导航栏 Logo​

导航栏项目​

导航栏链接​

导航栏下拉菜单​

导航栏文档链接​

链接到侧边栏的导航栏​

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

导航栏文档版本​

导航栏本地化下拉菜单​

导航栏搜索​

带自定义 HTML 的导航栏​

自动隐藏粘性导航栏​

导航栏样式​

代码块​

主题​

默认语言​

页脚​

页脚链接​

目录​

Hooks​

useColorMode​

国际化（i18n）​

翻译文件位置​

文件系统结构示例​

通用配置

颜色模式

元图片

元数据

公告栏

插件

文档

博客

导航栏

导航栏 Logo

导航栏项目

导航栏链接

导航栏下拉菜单

导航栏文档链接

链接到侧边栏的导航栏

导航栏文档版本下拉菜单

导航栏文档版本

导航栏本地化下拉菜单

导航栏搜索

带自定义 HTML 的导航栏

自动隐藏粘性导航栏

导航栏样式

代码块

主题

默认语言

页脚

页脚链接

目录

Hooks

`useColorMode`

国际化（i18n）

翻译文件位置

文件系统结构示例