theme-configuration

docusaurus.config.js

export default {
  themeConfig: {
    navbar: {
      items: [
        {
          to: 'docs/introduction',
          // 只使用 "to" 或 "href" 中的一个
          // href: 'https://www.facebook.com',
          label: '简介',
          // 只使用 "label" 或 "html" 中的一个
          // html: '<b>Introduction</b>'
          position: 'left',
          activeBaseRegex: 'docs/(next|v8)',
          target: '_blank',
        },
      ],
    },
  },
};

导航栏下拉菜单

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

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

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

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

可接受的字段：

名称	类型	默认值	描述
type	'dropdown'	可选	将此项目的类型设置为下拉菜单。
label	string	必需	要为此项目显示的名称。
items	[LinkLikeItem](#navbar-dropdown)[]	必需	要包含在下拉菜单中的项目。
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](#navbar-dropdown)[]	[]	在下拉菜单的开头添加其他下拉菜单项。
dropdownItemsAfter	[LinkLikeItem](#navbar-dropdown)[]	[]	在下拉菜单的结尾添加其他下拉菜单项。
docsPluginId	string	'default'	文档版本控制所属的文档插件的 ID。
dropdownActiveClassDisabled	boolean	false	浏览文档时不添加链接活动类。

示例配置：

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](#navbar-dropdown)[]	[]	在下拉菜单的开头添加其他下拉菜单项。
dropdownItemsAfter	[LinkLikeItem](#navbar-dropdown)[]	[]	在下拉菜单的结尾添加其他下拉菜单项。
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 的导航栏

您还可以使用此导航栏项目类型在导航栏项目内呈现您自己的 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,
    },
  },
};

导航栏样式

主题配置

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

常规配置

颜色模式

经典主题默认提供亮模式和暗模式支持，并带有用户可切换的导航栏开关。

可以在 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	徽标对象的自定义。
items	NavbarItem[]	[]	导航栏项列表。请参见下面的规范。
hideOnScroll	boolean	false	用户向下滚动时是否隐藏导航栏。
style	'primary' | 'dark'	与主题相同	设置导航栏样式，忽略暗/亮主题。

导航栏徽标

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

为了改进暗模式支持，您还可以为该模式设置不同的徽标。

可接受的字段：

名称	类型	默认值	描述
alt	string	undefined	徽标图像的替代文本。
src	string	必需	徽标图像的 URL。默认情况下会附加基本 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 风格，使用驼峰式命名属性。

示例配置：

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 应该会自动将活动链接样式应用于链接，但您可以在极端情况下使用 activeBasePath。对于应该在多个不同路径上处于活动状态的链接的情况（例如，当您在同一侧边栏下有多个文档文件夹时），您可以使用 activeBaseRegex。activeBaseRegex 是 activeBasePath 的更灵活的替代方案，并且优先于它——Docusaurus 将其解析为一个正则表达式，该表达式将针对当前 URL 进行测试。

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

可接受的字段：

名称	类型	默认值	描述
type	'default'	可选	将此项目的类型设置为链接。
label	string	必需	要为此项目显示的名称。
html	string	可选	与 label 相同，但呈现纯 HTML 而不是文本内容。
to	string	必需	客户端路由，用于在网站内导航。基本 URL 将自动添加到此值前面。
href	string	必需	全页导航，用于在网站外部导航。 只能使用 to 或 href 之一。
prependBaseUrlToHref	boolean	false	将基本 URL 添加到 href 值前面。
position	'left' | 'right'	'left'	此项目应显示在导航栏的哪一侧。
activeBasePath	string	to / href	要将活动类样式应用于以该路径开头的所有路由。这通常是不必要的。
activeBaseRegex	string	undefined	如果需要，则为 activeBasePath 的替代方案。
className	string	''	自定义 CSS 类（用于设置任何项目的样式）。

备注

除了上述字段外，您还可以指定可以应用于 HTML 链接的其他任意属性。

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

目前，有两个可能的样式选项：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 向页脚添加徽标和版权信息。徽标可以放置在 静态文件夹 中。徽标 URL 的工作方式与导航栏徽标相同。

可接受的字段：

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

示例配置：

docusaurus.config.js

export default {
  themeConfig: {
    footer: {
      logo: {
        alt: 'Meta 开源徽标',
        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	必需	客户端路由，用于在网站内导航。基本 URL 将自动添加到此值前面。
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="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>
          `,
      },
    ],
  },
};

目录

您可以通过 themeConfig.tableOfContents 调整默认目录。

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

示例配置：

docusaurus.config.js

export default {
  themeConfig: {
    tableOfContents: {
      minHeadingLevel: 2,
      maxHeadingLevel: 5,
    },
  },
};

钩子

useColorMode

一个用于访问颜色上下文的 React 钩子。此上下文包含用于设置亮模式和暗模式的函数，并公开一个布尔变量，指示当前正在使用的模式。

用法示例：

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

国际化

请先阅读 国际化介绍 。

翻译文件位置

• 基本路径 : 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