主题配置

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

通用

色彩模式

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

可以通过 colorMode 对象自定义色彩模式支持。

接受的字段：

参数	类型	默认值	描述
defaultMode	'light' | 'dark'	'light'	用户首次访问网站时的色彩模式。
disableSwitch	boolean	false	在导航栏隐藏按钮。 如果你想要只支持一种色彩模式很有用。
respectPrefersColorScheme	boolean	false	是否使用 prefers-color-scheme 媒体查询，从而使用用户系统的首选项，而不是硬代码的 defaultMode。

示例配置：

docusaurus.config.js

module.exports = {
  themeConfig: {
    colorMode: {
      defaultMode: 'light',
      disableSwitch: false,
      respectPrefersColorScheme: false,
    },
  },
};

注意

如果使用 respectPrefersColorScheme: true，defaultMode 会被用户系统的偏好设置覆盖。

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

元数据图像

你可以配置用于元标签的默认图像，尤其是 og:image 和 twitter:image。

接受的字段：

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

示例配置：

docusaurus.config.js

module.exports = {
  themeConfig: {
    image: 'img/docusaurus.png',
  },
};

元数据

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

接受的字段：

参数	类型	默认值	描述
metadata	Metadata[]	[]	所有字段都会被直接传递给 <meta /> 标签。 可选的字段包括 id、name、property、content、itemprop 等。

示例配置：

docusaurus.config.js

module.exports = {
  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

module.exports = {
  themeConfig: {
    announcementBar: {
      id: 'support_us',
      content:
        '我们正打算翻新文档，请填写<a target="_blank" rel="noopener noreferrer" href="#">这个调查</a>',
      backgroundColor: '#fafbfc',
      textColor: '#091E42',
      isCloseable: false,
    },
  },
};

导航栏

接受的字段：

参数	类型	默认值	描述
title	string	undefined	导航栏标题。
logo	见下文	undefined	图标对象的自定义。
items	NavbarItem[]	[]	导航栏项目列表。 见下文的说明。
hideOnScroll	boolean	false	当用户向下滚动时，导航栏是否隐藏。
style	'primary' | 'dark'	与色彩模式一致	设置导航栏样式，忽略暗黑/浅色色彩模式。

导航栏图标

图标可以放在静态文件夹里。 图标链接的 URL 会被默认设置为网站的 base URL。 尽管你可以为图标指定自己的 URL，但如果链接是外部的，它会打开一个新标签页。 此外，你还可以覆盖图标链接的 target 属性值，如果你把文档网站托管在主网站的一个子目录中，这个配置会很有用。这种情况下，你可能不需要在链接到主网站的时候打开新标签页。

为了改善暗黑模式支持，你也可以为暗黑模式设置一个不同的图标。

接受的字段：

参数	类型	默认值	描述
alt	string	undefined	图片的 alt 属性。
src	string	必填	图片的 URL。 Base URL 会被默认添加。
srcDark	string	logo.src	暗黑模式下使用的替代图像 URL。
href	string	siteConfig.baseUrl	点击图标时跳转到的链接。
width	string | number	undefined	指定 width 属性。
height	string | number	undefined	指定 height 属性。
target	string	根据 href 计算（外部链接会在新标签页中打开，其他链接在本页中打开）	链接的 target 属性。控制了链接会在新标签页还是当前页中打开。
className	string	undefined	图片的 CSS 类名。
style	object	undefined	内联 CSS 样式对象。 React/JSX 风格，所有属性都是驼峰格式 (camelCase)。

示例配置：

docusaurus.config.js

module.exports = {
  themeConfig: {
    navbar: {
      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

module.exports = {
  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 仓库',
        },
      ],
    },
  },
};

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

导航栏链接

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

React Router 会自动给链接应用活跃样式，但在边缘情况下，你可以使用 activeBasePath。 对于链接应该在几个不同路径上激活的情况（比如你在同一个侧边栏下有多个文件夹）， 你可以使用 activeBaseRegex。 activeBaseRegex 是一个比 activeBasePath 更灵活的替代选项，并且优先于后者——Docusaurus 会把它作为正则表达式解析，并与当前的 URL 匹配。

外部链接会自动获得 target="_blank" rel="noopener noreferrer" 属性。

接受的字段：

参数	类型	默认值	描述
type	'default'	可选	把这个项目的类型设置为链接。
label	string	必填	项目显示的名称。
html	string	可选	和 label 一样，但渲染纯 HTML 而不是文字内容。
to	string	必填	客户端路由，用于站内导航。 会自动在开头添加 base URL。
href	string	必填	整页导航，用于站外跳转。 只能使用 to 或 href 中的一个。
prependBaseUrlToHref	boolean	false	在 href 前添加 base URL。
position	'left' | 'right'	'left'	项目应该出现在导航栏的哪一侧。
activeBasePath	string	to / href	在以此路径开始的所有路由上应用活跃类样式。 通常没有必要设置。
activeBaseRegex	string	undefined	如果有需要，可以替代 activeBasePath。
className	string	''	自定义 CSS 类（用于任何项目的样式）。

备注

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

示例配置：

docusaurus.config.js

module.exports = {
  themeConfig: {
    navbar: {
      items: [
        {
          to: 'docs/introduction',
          // "to" 和 "href" 只应该用一个
          // href: 'https://www.facebook.com',
          label: '引言',
          // Only one of "label" or "html" should be used
          // 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

module.exports = {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'dropdown',
          label: '社区',
          position: 'left',
          items: [
            {
              label: 'Facebook',
              href: 'https://www.facebook.com',
            },
            {
              type: 'doc',
              label: '社交',
              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

module.exports = {
  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

module.exports = {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'docSidebar',
          position: 'left',
          sidebarId: 'api',
          label: 'API',
        },
      ],
    },
  },
};

sidebars.js

module.exports = {
  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	不要在浏览文档时添加链接活跃类名。

示例配置：

docusaurus.config.js

module.exports = {
  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

module.exports = {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'docsVersion',
          position: 'left',
          to: '/path',
          label: '标签',
        },
      ],
    },
  },
};

导航栏语言下拉菜单

如果你使用 i18n 功能，这个特别的的导航栏项目类型会渲染一个下拉菜单，包含了你的网站上所有可用的语言。

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

接受的字段：

参数	类型	默认值	描述
type	'localeDropdown'	必填	把这个项目的类型设置为语言下拉菜单。
position	'left' | 'right'	'left'	项目应该出现在导航栏的哪一侧。
dropdownItemsBefore	LinkLikeItem[]	[]	在下拉菜单开头添加额外的项目。
dropdownItemsAfter	LinkLikeItem[]	[]	在下拉菜单结尾添加额外的项目。

示例配置：

docusaurus.config.js

module.exports = {
  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

module.exports = {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'search',
          position: 'right',
        },
      ],
    },
  },
};

导航栏自定义 HTML 项目

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

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

docusaurus.config.js

module.exports = {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'html',
          position: 'right',
          value: '<button>提交反馈</button>',
        },
      ],
    },
  },
};

自动隐藏顶部导航栏

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

docusaurus.config.js

module.exports = {
  themeConfig: {
    navbar: {
      hideOnScroll: true,
    },
  },
};

导航栏样式

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

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

docusaurus.config.js

module.exports = {
  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

module.exports = {
  themeConfig: {
    prism: {
      theme: require('prism-react-renderer/themes/github'),
      darkTheme: require('prism-react-renderer/themes/dracula'),
    },
  },
};

备注

如果你使用了 Markdown 的行高亮语法，你可能需要为暗黑模式的语法高亮主题指定不同的行高亮背景颜色。 具体教程请参考文档。

默认语言

你可以设置代码块的默认语言。如果代码块开头的三个反引号（就是 ```）后没有添加语言，会使用默认语言。 注意必须传递合法的语言名。

示例配置：

docusaurus.config.js

module.exports = {
  themeConfig: {
    prism: {
      defaultLanguage: 'javascript',
    },
  },
};

页脚

你可以通过 themeConfig.foot 为页脚添加图标和版权声明。 图标可以放在静态文件夹中。 图标 URL 的工作方式和导航栏图标相同。

接受的字段：

参数	类型	默认值	描述
logo	Logo	undefined	图标对象的自定义。 详情可见导航栏图标。
copyright	string	undefined	在底部显示的版权信息。
style	'dark' | 'light'	'light'	页脚组件的色彩主题。
links	(Column | FooterLink)[]	[]	要显示的链接组。

示例配置：

docusaurus.config.js

module.exports = {
  themeConfig: {
    footer: {
      logo: {
        alt: 'Meta 开源图标',
        src: 'img/meta_oss_logo.png',
        href: 'https://opensource.fb.com',
        width: 160,
        height: 51,
      },
      copyright: `版权所有 © ${new Date().getFullYear()} 我的项目. 使用 Docusaurus 构建.`,
    },
  },
};

页脚链接

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

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

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

每个 FooterItem 接受的字段为：

参数	类型	默认值	描述
label	string	必填	链接显示的文字。
to	string	必填	客户端路由，用于站内导航。 会自动在开头添加 base URL。
href	string	必填	整页导航，用于站外跳转。 只能使用 to 或 href 中的一个。
html	string	undefined	渲染纯 HTML 而不是普通链接。 如果使用 html，就不应提供其他任何选项。

多列页脚配置示例：

docusaurus.config.js

module.exports = {
  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: 'Twitter',
            href: 'https://twitter.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

module.exports = {
  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="由Netlify 部署">
              <img src="https://www.netlify.com/img/global/badges/netlify-color-accent.svg" alt="由 Netlify 部署" width="114" height="51" />
            </a>
          `,
      },
    ],
  },
};

目录

你可以通过 themeConfig.tableOfContents 调整默认的目录样式。

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

示例配置：

docusaurus.config.js

module.exports = {
  themeConfig: {
    tableOfContents: {
      minHeadingLevel: 2,
      maxHeadingLevel: 5,
    },
  },
};

钩子函数

useColorMode

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

示例用法：

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

const Example = () => {
  const {colorMode, setColorMode} = useColorMode();

  return <h1>暗黑模式现在为{colorMode === 'dark' ? '开启状态': '关闭状态'}</h1>;
};

备注

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

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

i18n

请先阅读 i18n 简介。

翻译文件位置

• 基础路径：website/i18n/[语言]/docusaurus-theme-[主题名]
• 多实例路径：N/A
• JSON 文件：由 docusaurus write-translations 提取
• Markdown 文件：N/A

文件系统结构示例

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