主题配置

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

通用

颜色模式 - 暗色模式

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

您可通过以下配置来自定义颜色模式：

docusaurus.config.js

module.exports = {  // ...  themeConfig: {    // ...    colorMode: {      // "light" | "dark" (亮色 · 暗色)      defaultMode: 'light',
      // 隐藏导航栏的开关      // 适合您仅想使用一种颜色模式的情况      disableSwitch: false,
      // 是否使用 prefers-color-scheme media-query，      // 基于用户的系统偏好设置，而非硬编码的 defaultMode      respectPrefersColorScheme: false,
      // 暗色/亮色模式切换图标选项      switchConfig: {        // 暗色模式的切换图标        darkIcon: '🌙',
        // 应用暗色图标的 CSS，        // React 内联样式对象        // 参见 https://reactjs.org/docs/dom-elements.html#style        darkIconStyle: {          marginLeft: '2px',        },
        // 可使用类似 '\u2600' 的 Unicode 图标        // 5 个字符的 Unicode 需要使用括号包裹：'\u{1F602}'        lightIcon: '\u{1F602}',
        lightIconStyle: {          marginLeft: '1px',        },      },    },    // ...  },  // ...};

caution

若使用 respectPrefersColorScheme: true，defaultMode 将被用户系统的偏好设置覆盖。

若您只想支持单一颜色模式，您应该想忽略用户系统的偏好设置。

元数据标签

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

docusaurus.config.js

module.exports = {  // ...  themeConfig: {    // 相对您网站的 "static" 目录。    // 不可为 SVG 格式。 可为外部链接。    image: 'img/docusaurus.png',    // ...  },};

元数据

您可配置额外的 HTML 元数据（并覆盖现有数据）。

docusaurus.config.js

module.exports = {  // ...  themeConfig: {    metadatas: [{name: 'twitter:card', content: 'summary'}],    // ...  },};

公告栏

有时候，您需要在网站上公布内容。 这种情况下，您可以添加一个公告栏。 这是位于导航栏上方的一个不固定且可忽略的面板。

docusaurus.config.js

module.exports = {  // ...  themeConfig: {    announcementBar: {      id: 'support_us', // 用于辨别此消息的值。      content:        '我们想进一步改善文档，请帮忙填写一下<a target="_blank" rel="noopener noreferrer" href="#">此问卷</a>',      backgroundColor: '#fafbfc', // 默认为 `#fff`.      textColor: '#091E42', // 默认为 `#000`.      isCloseable: false, // 默认为 `true`.    },    // ...  },};

i18n

请先阅读 i18n 简介。

翻译文件位置

• 基础路径: website/i18n/<locale>/docusaurus-theme-<themeName>
• 多实例路径: N/A
• JSON files: extracted with docusaurus write-translations
• Markdown files: N/A

文件系统结构示例

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

钩子函数

使用主题文本

执行hook接收主题内容 This context contains functions for setting light and dark mode and exposes boolean variable, indicating which mode is currently in use.

示例用法：

import React from 'react';//高亮下一行import useThemeContext from '@theme/hooks/useThemeContext';
const Example = () => {  // 高亮下一行  const {isDarkTheme, setLightTheme, setDarkTheme} = useThemeContext();
  return <h1>Dark mode is now {isDarkTheme ? 'on': 'off'}</h1>;};

note

组件useThemeContext一定是 Layout的子项

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

导航栏

导航栏标题 & 标签

你可以通过 themeConfig.navbar 添加一个标签和标题。 标志可以放置在 静态文件夹 中。 标签URL将被默认设置位你网站的基本URL 尽管你可以指定自己的URL作为标签，但如果他有外部链接，他将会打开一个新页。 此外，您可以覆盖徽标链接的目标属性值， 如果您正在主网站的子目录中托管文档网站，它可以马上到来。 在这种情况下，您可能不需要在主网站的徽标上链接，将在一个新标签中打开.

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

docusaurus.config.js

module.exports = {  // ...  themeConfig: {    navbar: {      title: 'Site Title',      logo: {        alt: 'Site Logo',        src: 'img/logo.svg',        srcDark: 'img/logo_dark.svg', // 默认 `logo.src`.        href: 'https://docusaurus.io/', // Default to `siteConfig.baseUrl`.        target: '_self', // 默认情况下，这个值是基于‘herf’属性计算 (外部链接将会打开新页, 其他都在当前页).      },    },    // ...  },};

导航栏项目

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

docusaurus.config.js

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

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

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

React Router 应该自动应用激活链接样式到链接，但你可以在边缘情况下使用 ActiveBasePath。 对于链接应该在几个不同路径上激活的情况(例如你在同一个侧边栏下有多个操作文件夹的情况)， 您可以使用 activeBaseRegex。 ActiveBaseRegex 是一个 ActiveBasePath 的更灵活的替代品，并且优先于它 -- Docusaurus 解析它为一个正则表达式，并用当前的 URL 测试。

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

Accepted fields:

字段	Value	Explanation	Required	默认值
label	string	The name to be shown for this item.	Yes
to	string	Client-side routing, used for navigating within the website. The baseUrl will be automatically prepended to this value.	Yes
href	string	A full-page navigation, used for navigating outside of the website. Only one of to or href should be used.	Yes
prependBaseUrlToHref	boolean	Prepends the baseUrl to href values.	No	false
position	'left' | 'right'	The side of the navbar this item should appear on.	No	'left'
activeBasePath	string	To apply the active class styling on all routes starting with this path. This usually isn't necessary.	No	to / href
activeBaseRegex	string	Alternative to activeBasePath if required.	No	undefined
className	string	Custom CSS class (for styling any item).	No	''

Example configuration:

docusaurus.config.js

module.exports = {  themeConfig: {    navbar: {      items: [        {          to: 'docs/introduction',          // Only one of "to" or "href" should be used          // href: 'https://www.facebook.com',          label: 'Introduction',          position: 'left',          activeBaseRegex: 'docs/(next|v8)',        },      ],    },  },};

导航栏下拉列表

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

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

• Navbar link
• 导航栏 文档 链接
• Navbar doc version

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:

字段	Value	Explanation	Required	默认值
label	string	The name to be shown for this item.	Yes
items	LinkLikeItem[]	The items to be contained in the dropdown.	Yes
position	'left' | 'right'	The side of the navbar this item should appear on.	No	'left'

Example configuration:

docusaurus.config.js

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

导航栏 文档 链接

如果您想要链接到一个特定的文档， 这个特殊的导航栏项目类型将会呈现链接到提供的 docid。 只要您浏览同一侧边栏的文档，它将获得 navbar__link--active 类。

Accepted fields:

字段	Value	Explanation	Required	默认值
docId	string	The ID of the doc that this item links to.	Yes
label	string	The name to be shown for this item.	No	docId
position	'left' | 'right'	The side of the navbar this item should appear on.	No	'left'
activeSidebarClassName	string	The CSS class name to apply when this doc's sidebar is active.	No	'navbar__link--active'
docsPluginId	string	The ID of the docs plugin that the doc belongs to.	No	'default'

Example configuration:

docusaurus.config.js

module.exports = {  themeConfig: {    navbar: {      items: [        {          type: 'doc',          position: 'left',          docId: 'introduction',          label: 'Docs',        },      ],    },  },};

导航栏 文档版本下拉列表

如果你使用带有版本的文档，这个特殊的导航栏项目类型将会呈现你所有站点可用的版本的下拉。

用户可以从一个版本切换到另一个版本。 当保持在同一文档上(只要文档id是跨版本不变)。

Accepted fields:

字段	Value	Explanation	Required	默认值
position	'left' | 'right'	The side of the navbar this item should appear on.	No	'left'
dropdownItemsBefore	LinkLikeItem[]	Add additional dropdown items at the beginning of the dropdown.	No	[]
dropdownItemsAfter	LinkLikeItem[]	Add additional dropdown items at the end of the dropdown.	No	[]
docsPluginId	string	The ID of the docs plugin that the doc versioning belongs to.	No	'default'
dropdownActiveClassDisabled	boolean	Do not add the link active class when browsing docs.	No	false

Example configuration:

docusaurus.config.js

module.exports = {  themeConfig: {    navbar: {      items: [        {          type: 'docsVersionDropdown',          position: 'left',          dropdownItemsAfter: [{to: '/versions', label: 'All versions'}],          dropdownActiveClassDisabled: true,        },      ],    },  },};

导航栏文档版本

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:

字段	Value	Explanation	Required	默认值
label	string	The name to be shown for this item.	No	The active/latest version label.
to	string	The internal link that this item points to.	No	The active/latest version.
position	'left' | 'right'	The side of the navbar this item should appear on.	No	'left'
docsPluginId	string	The ID of the docs plugin that the doc versioning belongs to.	No	'default'

Example configuration:

docusaurus.config.js

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

导航栏区域下拉列表

如果你使用 i18n feature, 这种特殊的导航栏项目类型将显示一个包含您网站所有可用语言环境的下拉菜单。

用户将能够在同一页面上从一个区域切换到另一个区域。

Accepted fields:

字段	Value	Explanation	Required	默认值
position	'left' | 'right'	The side of the navbar this item should appear on.	No	'left'
dropdownItemsBefore	LinkLikeItem[]	Add additional dropdown items at the beginning of the dropdown.	No	[]
dropdownItemsAfter	LinkLikeItem[]	Add additional dropdown items at the end of the dropdown.	No	[]

Example configuration:

docusaurus.config.js

module.exports = {  themeConfig: {    navbar: {      items: [        {          type: 'localeDropdown',          position: 'left',          dropdownItemsAfter: [            {              to: 'https://my-site.com/help-us-translate',              label: 'Help us translate',            },          ],        },      ],    },  },};

导航栏搜索

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

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

字段	Value	Explanation	Required	默认值
position	'left' | 'right'	The side of the navbar this item should appear on.	No	'left'

docusaurus.config.js

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

自动隐藏置顶导航栏

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

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 高亮代码块。

主题

默认情况下，我们使用 Palenight 作为语法高亮主题。 您可以从 个可用主题列表 指定一个自定义主题。 如果你想在网站处于暗色模式时使用不同的语法高亮主题，你也可以这样做。

docusaurus.config.js

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

note

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

默认语言

如果在开头的三次背面后没有添加语言，你可以设置代码块的默认语言(例如```)。 请注意，必须传递有效的 language name：

docusaurus.config.js

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

页脚

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

docusaurus.config.js

  // ...  footer: {    logo: {      alt: 'Facebook Open Source Logo',      src: 'img/oss_logo.png',      href: 'https://opensource.facebook.com',    },    copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`,  }

页脚链接

您可以通过 themeConfig.footer.links 来添加链接至页脚。

docusaurus.config.js

module.exports = {  // ...  footer: {    links: [      {        // 这些链接的章节标签        title: 'Docs',        items: [          {            // 链接标签            label: 'Style Guide',            // 客户端路由，用于导航网站内的导航.            // BaseUrl 将自动添加到这个值。            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: 'Twitter',            href: 'https://twitter.com/docusaurus',          },          {            //呈现html传递而不是简单的链接            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" />                </a>              `,          },        ],      },    ],  },};