主题配置

¥Theme configuration

此配置适用于所有 主题。

¥This configuration applies to all main themes.

常见的

¥Common

色彩模式

¥Color mode

经典主题默认提供浅色和夜间模式支持，并为用户提供导航栏开关。

¥The classic theme provides by default light and dark mode support, with a navbar switch for the user.

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

¥It is possible to customize the color mode support within the colorMode object.

接受的字段：

¥Accepted fields:

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

配置示例：

¥Example configuration:

docusaurus.config.js

export default {
  themeConfig: {
    colorMode: {
      defaultMode: 'light',
      disableSwitch: false,
      respectPrefersColorScheme: false,
    },
  },
};

警告

对于 respectPrefersColorScheme: true，defaultMode 会被用户系统首选项覆盖。

¥With respectPrefersColorScheme: true, the defaultMode is overridden by user system preferences.

如果你只想支持一种颜色模式，你可能想忽略用户系统首选项。

¥If you only want to support one color mode, you likely want to ignore user system preferences.

元图片

¥Meta image

你可以配置将用于元标记的默认图片，特别是 og:image 和 twitter:image。

¥You can configure a default image that will be used for your meta tag, in particular og:image and twitter:image.

接受的字段：

¥Accepted fields:

名称	类型	默认	描述
image	string	undefined	站点的元图片 URL。相对于你网站的 "static" 目录。不能是 SVG。也可以是外部 URL。

配置示例：

¥Example configuration:

docusaurus.config.js

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

元数据

¥Metadata

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

¥You can configure additional HTML metadata (and override existing ones).

接受的字段：

¥Accepted fields:

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

配置示例：

¥Example configuration:

docusaurus.config.js

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

公告栏

¥Announcement bar

有时你想在你的网站上宣布一些事情。针对这种情况，你可以添加公告栏。这是导航栏上方的一个非固定且可选的可关闭面板。所有配置都在 announcementBar 对象中。

¥Sometimes you want to announce something in your website. Just for such a case, you can add an announcement bar. This is a non-fixed and optionally dismissible panel above the navbar. All configuration are in the announcementBar object.

接受的字段：

¥Accepted fields:

名称	类型	默认	描述
id	string	'announcement-bar'	任何可识别此消息的值。
content	string	''	公告的文本内容。HTML 将被插入。
backgroundColor	string	'#fff'	整个栏的背景颜色。
textColor	string	'#000'	公告文本颜色。
isCloseable	boolean	true	是否可以通过 '×' 按钮关闭此公告。

配置示例：

¥Example configuration:

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

插件

¥Plugins

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

¥Our main themes offer additional theme configuration options for Docusaurus core content plugins.

文档

¥Docs

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

配置示例：

¥Example configuration:

docusaurus.config.js

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

博客

¥Blog

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

配置示例：

¥Example configuration:

docusaurus.config.js

export default {
  themeConfig: {
    blog: {
      sidebar: {
        groupByYear: true,
      },
    },
  },
};

导航栏

¥Navbar

接受的字段：

¥Accepted fields:

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

导航栏徽标

¥Navbar logo

该标志可以放置在 静态文件夹。默认情况下，徽标 URL 设置为你网站的基本 URL。虽然你可以为徽标指定自己的 URL，但如果它是外部链接，它将在新选项卡中打开。此外，你可以覆盖徽标链接的目标属性的值，如果你在主网站的子目录中托管文档网站，它会派上用场，在这种情况下，你可能不需要徽标中的链接 主网站将在新选项卡中打开。

¥The logo can be placed in static folder. Logo URL is set to base URL of your site by default. Although you can specify your own URL for the logo, if it is an external link, it will open in a new tab. In addition, you can override a value for the target attribute of logo link, it can come in handy if you are hosting docs website in a subdirectory of your main website, and in which case you probably do not need a link in the logo to the main website will open in a new tab.

为了提高夜间模式支持，你还可以为此模式设置不同的徽标。

¥To improve dark mode support, you can also set a different logo for this mode.

接受的字段：

¥Accepted fields:

名称	类型	默认	描述
alt	string	undefined	徽标图片的 Alt 标签。
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 风格，使用驼峰命名法属性。

配置示例：

¥Example configuration:

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.nodejs.cn/',
        target: '_self',
        width: 32,
        height: 32,
        className: 'custom-navbar-logo-class',
        style: {border: 'solid red'},
      },
    },
  },
};

导航栏项目

¥Navbar items

你可以通过 themeConfig.navbar.items 将项目添加到导航栏。

¥You can add items to the navbar via 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 字段，这些项目可以具有不同的行为。以下部分将向你介绍所有可用的导航栏项目类型。

¥The items can have different behaviors based on the type field. The sections below will introduce you to all the types of navbar items available.

导航栏链接

¥Navbar link

默认情况下，导航栏项目是常规链接（内部或外部）。

¥By default, Navbar items are regular links (internal or external).

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

¥React Router should automatically apply active link styling to links, but you can use activeBasePath in edge cases. For cases in which a link should be active on several different paths (such as when you have multiple doc folders under the same sidebar), you can use activeBaseRegex. activeBaseRegex is a more flexible alternative to activeBasePath and takes precedence over it -- Docusaurus parses it into a regular expression that is tested against the current URL.

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

¥Outbound (external) links automatically get target="_blank" rel="noopener noreferrer" attributes.

接受的字段：

¥Accepted fields:

名称	类型	默认	描述
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 链接的其他任意属性。

¥In addition to the fields above, you can specify other arbitrary attributes that can be applied to a HTML link.

配置示例：

¥Example configuration:

docusaurus.config.js

export default {
  themeConfig: {
    navbar: {
      items: [
        {
          to: 'docs/introduction',
          // Only one of "to" or "href" should be used
          // href: 'https://www.facebook.com',
          label: 'Introduction',
          // Only one of "label" or "html" should be used
          // html: '<b>Introduction</b>'
          position: 'left',
          activeBaseRegex: 'docs/(next|v8)',
          target: '_blank',
        },
      ],
    },
  },
};

导航栏下拉菜单

¥Navbar dropdown

dropdown 类型的导航栏项目具有附加的 items 字段，即导航栏项目的内部数组。

¥Navbar items of the type dropdown has the additional items field, an inner array of navbar items.

导航栏下拉项仅接受以下 "link-like" 项类型：

¥Navbar dropdown items only accept the following "link-like" item types:

• 导航栏链接

  ¥Navbar link

• 导航栏文档链接

  ¥Navbar doc link

• 导航栏文档版本

  ¥Navbar docs version

• 导航栏文档侧边栏

  ¥Navbar doc sidebar

• 带有自定义 HTML 的导航栏

  ¥Navbar with custom HTML

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

¥Note that the dropdown base item is a clickable link as well, so this item can receive any of the props of a plain navbar link.

接受的字段：

¥Accepted fields:

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

配置示例：

¥Example configuration:

docusaurus.config.js

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

导航栏文档链接

¥Navbar doc link

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

¥If you want to link to a specific doc, this special navbar item type will render the link to the doc of the provided docId. It will get the class navbar__link--active as long as you browse a doc of the same sidebar.

接受的字段：

¥Accepted fields:

名称	类型	默认	描述
type	'doc'	必需的	将此项目的类型设置为文档链接。
docId	string	必需的	该项目链接到的文档的 ID。
label	string	docId	该项目要显示的名称。
position	'left' | 'right'	'left'	该项目应出现在导航栏的一侧。
docsPluginId	string	'default'	文档所属的文档插件的 ID。

配置示例：

¥Example configuration:

docusaurus.config.js

export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'doc',
          position: 'left',
          docId: 'introduction',
          label: 'Docs',
        },
      ],
    },
  },
};

导航栏链接到侧边栏

¥Navbar linked to a sidebar

你可以将导航栏项目链接到给定侧边栏的第一个文档链接（可以是文档链接或生成的类别索引），而无需对文档 ID 进行硬编码。

¥You can link a navbar item to the first document link (which can be a doc link or a generated category index) of a given sidebar without having to hardcode a doc ID.

接受的字段：

¥Accepted fields:

名称	类型	默认	描述
type	'docSidebar'	必需的	将此导航栏项目的类型设置为侧边栏的第一个文档。
sidebarId	string	必需的	该项目链接到的侧边栏的 ID。
label	string	第一个文档链接的侧边栏标签	该项目要显示的名称。
position	'left' | 'right'	'left'	该项目应出现在导航栏的一侧。
docsPluginId	string	'default'	侧边栏所属的文档插件的 ID。

提示

如果你的侧边栏经常更新且顺序不稳定，请使用此导航栏项目类型。

¥Use this navbar item type if your sidebar is updated often and the order is not stable.

配置示例：

¥Example configuration:

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

导航栏文档版本下拉列表

¥Navbar docs version dropdown

如果你使用带有版本控制的文档，这种特殊的导航栏项目类型将渲染一个包含站点所有可用版本的下拉列表。

¥If you use docs with versioning, this special navbar item type that will render a dropdown with all your site's available versions.

用户将能够从一个版本切换到另一个版本，同时保留在同一个文档上（只要文档 ID 在各个版本中保持不变）。

¥The user will be able to switch from one version to another, while staying on the same doc (as long as the doc ID is constant across versions).

接受的字段：

¥Accepted fields:

名称	类型	默认	描述
type	'docsVersionDropdown'	必需的	将此项目的类型设置为文档版本下拉列表。
position	'left' | 'right'	'left'	该项目应出现在导航栏的一侧。
dropdownItemsBefore	LinkLikeItem[]	[]	在下拉列表的开头添加其他下拉项目。
dropdownItemsAfter	LinkLikeItem[]	[]	在下拉列表末尾添加其他下拉项目。
docsPluginId	string	'default'	文档版本控制所属的文档插件的 ID。
dropdownActiveClassDisabled	boolean	false	浏览文档时不要添加链接活动类。

配置示例：

¥Example configuration:

docusaurus.config.js

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

导航栏文档版本

¥Navbar docs version

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

¥If you use docs with versioning, this special navbar item type will link to the active/browsed version of your doc (depends on the current URL), and fallback to the latest version.

接受的字段：

¥Accepted fields:

名称	类型	默认	描述
type	'docsVersion'	必需的	将此项的类型设置为文档版本链接。
label	string	有效/最新版本标签。	该项目要显示的名称。
to	string	有效/最新版本。	该项目指向的内部链接。
position	'left' | 'right'	'left'	该项目应出现在导航栏的一侧。
docsPluginId	string	'default'	文档版本控制所属的文档插件的 ID。

配置示例：

¥Example configuration:

docusaurus.config.js

export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'docsVersion',
          position: 'left',
          to: '/path',
          label: 'label',
        },
      ],
    },
  },
};

导航栏区域设置下拉菜单

¥Navbar locale dropdown

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

¥If you use the i18n feature, this special navbar item type will render a dropdown with all your site's available locales.

用户将能够从一个区域设置切换到另一个区域设置，同时保持在同一页面上。

¥The user will be able to switch from one locale to another, while staying on the same page.

接受的字段：

¥Accepted fields:

名称	类型	默认	描述
type	'localeDropdown'	必需的	将此项目的类型设置为区域设置下拉列表。
position	'left' | 'right'	'left'	该项目应出现在导航栏的一侧。
dropdownItemsBefore	LinkLikeItem[]	[]	在下拉列表的开头添加其他下拉项目。
dropdownItemsAfter	LinkLikeItem[]	[]	在下拉列表末尾添加其他下拉项目。
queryString	string	undefined	要附加到 URL 的查询字符串。

配置示例：

¥Example configuration:

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

导航栏搜索

¥Navbar search

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

¥If you use the search, the search bar will be the rightmost element in the navbar.

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

¥However, with this special navbar item type, you can change the default location.

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

docusaurus.config.js

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

带有自定义 HTML 的导航栏

¥Navbar with custom HTML

你还可以使用此导航栏项目类型在导航栏项目内渲染你自己的 HTML 标记。

¥You can also render your own HTML markup inside a navbar item using this navbar item type.

名称	类型	默认	描述
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>',
        },
      ],
    },
  },
};

自动隐藏粘性导航栏

¥Auto-hide sticky navbar

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

¥You can enable this cool UI feature that automatically hides the navbar when a user starts scrolling down the page, and show it again when the user scrolls up.

docusaurus.config.js

export default {
  themeConfig: {
    navbar: {
      hideOnScroll: true,
    },
  },
};

导航栏样式

¥Navbar style

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

¥You can set the static Navbar style without disabling the theme switching ability. The selected style will always apply no matter which theme user have selected.

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

¥Currently, there are two possible style options: dark and primary (based on the --ifm-color-primary color). You can see the styles preview in the Infima documentation.

docusaurus.config.js

export default {
  themeConfig: {
    navbar: {
      style: 'primary',
    },
  },
};

CodeBlock

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

¥Docusaurus uses Prism React Renderer to highlight code blocks. All configuration are in the prism object.

接受的字段：

¥Accepted fields:

名称	类型	默认	描述
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'},
  },
];

主题

¥Theme

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

¥By default, we use Palenight as syntax highlighting theme. You can specify a custom theme from the list of available themes. You may also use a different syntax highlighting theme when the site is in dark mode.

配置示例：

¥Example configuration:

docusaurus.config.js

import {themes as prismThemes} from 'prism-react-renderer';

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

注意

如果你使用行高亮 Markdown 语法，则可能需要为夜间模式语法高亮主题指定不同的高亮背景颜色。参见 指导文档。

¥If you use the line highlighting Markdown syntax, you might need to specify a different highlight background color for the dark mode syntax highlighting theme. Refer to the docs for guidance.

默认语言

¥Default language

如果在开始的三个反引号（即```）后没有添加语言，你可以为代码块设置默认语言。请注意，必须传递有效的 语言名称。

¥You can set a default language for code blocks if no language is added after the opening triple backticks (i.e. ```). Note that a valid language name must be passed.

配置示例：

¥Example configuration:

docusaurus.config.js

export default {
  themeConfig: {
    prism: {
      defaultLanguage: 'javascript',
    },
  },
};

页脚

¥Footer

你可以通过 themeConfig.footer 在页脚添加徽标和版权。标志可以放在 静态文件夹。徽标 URL 的工作方式与导航栏徽标相同。

¥You can add logo and a copyright to the footer via themeConfig.footer. Logo can be placed in static folder. Logo URL works in the same way of the navbar logo.

接受的字段：

¥Accepted fields:

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

配置示例：

¥Example configuration:

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

页脚链接

¥Footer Links

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

¥You can add links to the footer via themeConfig.footer.links. There are two types of footer configurations: multi-column footers and simple footers.

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

¥Multi-column footer links have a title and a list of FooterItems for each column.

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

每个 FooterItem 接受的字段：

¥Accepted fields of each FooterItem:

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

多列配置示例：

¥Example multi-column configuration:

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 的列表。

¥A simple footer just has a list of FooterItems displayed in a row.

简单配置示例：

¥Example simple configuration:

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

目录

¥Table of Contents

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

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

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

配置示例：

¥Example configuration:

docusaurus.config.js

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

钩子

¥Hooks

useColorMode

用于访问颜色上下文的 React hook。该上下文包含用于设置亮模式和夜间模式的函数，并公开布尔变量，指示当前正在使用哪种模式。

¥A React hook to access the color context. This context contains functions for setting light and dark mode and exposes boolean variable, indicating which mode is currently in use.

使用示例：

¥Usage example:

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

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

  return <h1>Dark mode is now {colorMode === 'dark' ? 'on' : 'off'}</h1>;
};

注意

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

¥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

• 基本路径：website/i18n/[locale]/docusaurus-theme-[themeName]

  ¥Base path: website/i18n/[locale]/docusaurus-theme-[themeName]

• 多实例路径：不适用

  ¥Multi-instance path: N/A

• JSON 文件：用 docusaurus write-translations 提取

  ¥JSON files: extracted with docusaurus write-translations

• Markdown 文件：不适用

  ¥Markdown files: N/A

文件系统结构示例

¥Example file-system structure

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