主题配置

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

常见的

颜色模式

经典主题提供默认的明暗模式支持，并为用户提供导航条开关。

可以在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被用户系统偏好覆盖。

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

元的形象

你可以为你的 meta 标签配置一个默认的图片，特别是og:image和twitter:image。

接受字段:

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

示例配置:

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'	Any value that will identify this message.
content	string	''	The text content of the announcement. HTML will be interpolated.
backgroundColor	string	'#fff'	Background color of the entire bar.
textColor	string	'#000'	Announcement text color.
isCloseable	boolean	true	Whether this announcement can be dismissed with a '×' button.

示例配置:

docusaurus.config.js

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

导航条

接受字段:

名字	类型	默认	描述
title	string	undefined	Title for the navbar.
logo	See below	undefined	Customization of the logo object.
items	NavbarItem[]	[]	A list of navbar items. See specification below.
hideOnScroll	boolean	false	Whether the navbar is hidden when the user scrolls down.
style	'primary' | 'dark'	Same as theme	Sets the navbar style, ignoring the dark/light theme.

导航 logo

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

为了提高暗模式的支持，你也可以为这个模式设置一个不同的标志。

接受字段:

名字	类型	默认	描述
alt	string	undefined	Alt tag for the logo image.
src	string	Required	URL to the logo image. Base URL is appended by default.
srcDark	string	logo.src	An alternative image URL to use in dark mode.
href	string	siteConfig.baseUrl	Link to navigate to when the logo is clicked.
width	string | number	undefined	Specifies the width attribute.
height	string | number	undefined	Specifies the height attribute.
target	string	Calculated based on href (external links will open in a new tab, all others in the current one).	The target attribute of the link; controls whether the link is opened in a new tab, the current one, or otherwise.
className	string	undefined	CSS class applied to the image.
style	object	undefined	CSS inline style object. React/JSX flavor, using camelCase properties.

示例配置:

docusaurus.config.js

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

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

根据type字段，项目可以有不同的行为。下面的小节将向您介绍所有可用的导航栏项类型。

导航链接

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

React Router 应该自动对链接应用活动链接样式，但在极端情况下，你可以使用activeBasePath。对于一个链接应该在几个不同的路径上激活的情况(比如当你在同一个侧边栏下有多个文档文件夹时)，你可以使用activeBaseRegex。activeBaseRegex是activeBasePath的一个更灵活的替代方案，并且优先于activeBasePath——Docusaurus 将其解析为一个正则表达式，并根据当前 URL 进行测试。

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

接受字段:

名字	类型	默认	描述
type	'default'	Optional	Sets the type of this item to a link.
label	string	Required	The name to be shown for this item.
html	string	Optional	Same as label, but renders pure HTML instead of text content.
to	string	Required	Client-side routing, used for navigating within the website. The baseUrl will be automatically prepended to this value.
href	string	Required	A full-page navigation, used for navigating outside of the website. Only one of to or href should be used.
prependBaseUrlToHref	boolean	false	Prepends the baseUrl to href values.
position	'left' | 'right'	'left'	The side of the navbar this item should appear on.
activeBasePath	string	to / href	To apply the active class styling on all routes starting with this path. This usually isn't necessary.
activeBaseRegex	string	undefined	Alternative to activeBasePath if required.
className	string	''	Custom CSS class (for styling any item).

备注

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

示例配置:

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",
          // Only one of "label" or "html" should be used
          // html: '<b>Introduction</b>'
          position: "left",
          activeBaseRegex: "docs/(next|v8)",
          target: "_blank",
        },
      ],
    },
  },
};

导航栏下拉列表

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

导航栏下拉项只接受以下类似链接的项类型:

• Navbar 链接
• Navbar 文档链接
• Navbar 文档版本
• Navbar 文档边栏
• Navbar 使用自定义 HTML

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

接受字段:

名字	类型	默认	描述
type	'dropdown'	Optional	Sets the type of this item to a dropdown.
label	string	Required	The name to be shown for this item.
items	LinkLikeItem[]	Required	The items to be contained in the dropdown.
position	'left' | 'right'	'left'	The side of the navbar this item should appear on.

示例配置:

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。

接受字段:

名字	类型	默认	描述
type	'doc'	Required	Sets the type of this item to a doc link.
docId	string	Required	The ID of the doc that this item links to.
label	string	docId	The name to be shown for this item.
position	'left' | 'right'	'left'	The side of the navbar this item should appear on.
docsPluginId	string	'default'	The ID of the docs plugin that the doc belongs to.

示例配置:

docusaurus.config.js

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

链接到侧边栏的导航栏

您可以将导航栏项链接到给定侧边栏的第一个文档链接(可以是文档链接或生成的类别索引)，而不必硬编码文档 ID。

接受字段:

名字	类型	默认	描述
type	'docSidebar'	Required	Sets the type of this navbar item to a sidebar's first document.
sidebarId	string	Required	The ID of the sidebar that this item is linked to.
label	string	First document link's sidebar label	The name to be shown for this item.
position	'left' | 'right'	'left'	The side of the navbar this item should appear on.
docsPluginId	string	'default'	The ID of the docs plugin that the sidebar belongs to.

提示

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

示例配置:

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", // The navbar item will be linking to this doc
    "docusaurus-core",
    {
      type: "autogenerated",
      dirName: "api",
    },
  ],
};

导航栏版本下拉列

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

用户将能够从一个版本切换到另一个版本，同时保持在同一个文档上(只要文档 ID 在不同版本之间保持不变)。

接受字段:

名字	类型	默认	描述
type	'docsVersionDropdown'	Required	将该项的类型设置为文档版本下拉列表。
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: "All versions" }],
          dropdownActiveClassDisabled: true,
        },
      ],
    },
  },
};

导航栏文档版本

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

接受字段:

名字	类型	默认	描述
type	'docsVersion'	Required	将该项的类型设置为文档版本链接。
label	string	The active/latest version label.	此项目要显示的名称。
to	string	The active/latest version.	此项目指向的内部链接。
position	'left' | 'right'	'left'	此项目应显示在导航条的一侧。
docsPluginId	string	'default'	文档版本所归属的文档插件的 ID。

示例配置:

docusaurus.config.js

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

导航条语言下拉列

如果您使用i18n 特性，这个特殊的导航栏项目类型将呈现一个包含站点所有可用区域设置的下拉菜单。

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

接受字段:

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

示例配置:

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，则搜索栏将是导航栏中最右边的元素。

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

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

docusaurus.config.js

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

带有自定义 HTML 的导航栏

您还可以使用此导航栏项类型在导航栏项中呈现您自己的 HTML 标记。

名字	类型	默认	描述
type	'html'	Required	将该项的类型设置为 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>Give feedback</button>",
        },
      ],
    },
  },
};

自动隐藏粘性导航条

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

docusaurus.config.js

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

导航栏样式

您可以在不禁用主题切换功能的情况下设置静态导航栏样式。无论用户选择了哪个主题，所选择的样式都将始终应用。

目前，有两种可能的样式选项:深色和初级(基于——ifm-color-primary颜色)。你可以在Infima 文档中看到样式预览。

docusaurus.config.js

module.exports = {
  themeConfig: {
    navbar: {
      style: "primary",
    },
  },
};

代码块

Docusaurus 使用Prism React Renderer来突出显示代码块。所有的配置都在prism对象中。

接受字段:

名字	类型	默认	描述
theme	PrismTheme	palenight	The Prism theme to use for light-theme code blocks.
darkTheme	PrismTheme	palenight	The Prism theme to use for dark-theme code blocks.
defaultLanguage	string	undefined	The default language to use for code blocks not declaring any explicit language.
magicComments	MagicCommentConfig[]	see below	The list of magic comments.

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.footer添加徽标和版权到页脚。Logo 可以放置在static 文件夹中。Logo URL 的工作方式与导航栏 Logo 相同。

接受字段:

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

示例配置:

docusaurus.config.js

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

页脚的链接

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

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

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

每个FooterItem的可接受字段:

名字	类型	默认	描述
label	string	Required	此链接要显示的文本。
to	string	Required	客户端路由，用于在网站内导航。baseUrl 将自动添加到该值之前。
href	string	Required	整页导航，用于网站外部导航。**只能使用to或href中的一个 **
html	string	undefined	呈现 HTML 直通，而不是简单的链接。如果使用html，则不应提供其他选项。

多列配置示例:

docusaurus.config.js

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

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="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

module.exports = {
  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>Dark mode is now {colorMode === "dark" ? "on" : "off"}</h1>;
};

备注

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

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

i18n

首先阅读i18n 介绍。

翻译文件位置

• 基本路径: website/i18n/[locale]/docusaurus-theme-[themeName]
• 多实例路径: N/A
• JSON 文件: extracted with docusaurus write-translations
• Markdown 文件: N/A

示例文件系统结构

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