跳到主要内容
版本：2.0.0-beta.21

主题配置

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

通用​

色彩模式​

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

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

接受的字段：

NameTypeDefaultDescription
defaultMode'light' | 'dark''light'The color mode when user first visits the site.
disableSwitchbooleanfalse在导航栏隐藏按钮。 如果你想要只支持一种色彩模式很有用。
respectPrefersColorSchemebooleanfalse是否使用 "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 stringundefined网站的元数据图像链接。 相对于你的网站的静态目录。 不能是 SVG。 可以是外部链接。

示例配置：

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

元数据​

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

接受的字段：

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

示例配置：

docusaurus.config.js
module.exports = {
  themeConfig: {
    metadata: [{name: 'twitter:card', content: 'summary'}],
  },
};

告示条​

有时候，你需要在网站上发布告示。 这种情况下，你可以添加一个告示条。 这是位于导航栏上方的一个面板，非固定而且可以关闭。 所有配置都在 announcementBar 对象中。

接受的字段：

名称类型默认值描述
idstring'announcement-bar'用于标识此消息的任何值。
contentstring''告示的文字内容。 HTML 也可以识别。
backgroundColorstring'#fff'整个告示条的背景颜色。
textColorstring'#000'告示条的文字颜色。
isCloseablebooleantrue告示条是否可以用 '×' 按钮关闭。

示例配置：

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

接受的字段：

NameTypeDefaultDescription

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

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

接受的字段：

NameTypeDefaultDescription

示例配置：

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

你可以通过向导航栏 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" 属性。

接受的字段：

NameTypeDefaultDescription
备注

除了上面的字段外，你可以指定其他任何 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 字段，一组内部的导航栏项目。

下拉菜单的内部项目只支持以下「类链接」的项目类型：

请注意下拉菜单的主项也是一个可点击的链接，所以它可以接受普通导航栏链接的任何属性。

接受的字段：

NameTypeDefaultDescription

示例配置：

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 类名。

接受的字段：

NameTypeDefaultDescription

示例配置：

docusaurus.config.js
module.exports = {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'doc',
          position: 'left',
          docId: 'introduction',
          label: '文档',
        },
      ],
    },
  },
};

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

接受的字段：

NameTypeDefaultDescription
提示

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

示例配置：

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 在版本之间保持不变）。

接受的字段：

NameTypeDefaultDescription

示例配置：

docusaurus.config.js
module.exports = {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'docsVersionDropdown',
          position: 'left',
          dropdownItemsAfter: [{to: '/versions', label: '所有版本'}],
          dropdownActiveClassDisabled: true,
        },
      ],
    },
  },
};

如果你使用文档版本化，这个特别的的导航栏项目类型会链接到你的文档的活跃版本（正浏览的版本；取决于当前的 URL）。如果没有版本处于活跃状态，则链接到最新版本。

接受的字段：

NameTypeDefaultDescription

示例配置：

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

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

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

接受的字段：

NameTypeDefaultDescription

示例配置：

docusaurus.config.js
module.exports = {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'localeDropdown',
          position: 'left',
          dropdownItemsAfter: [
            {
              to: 'https://my-site.com/help-us-translate',
              label: '帮助我们翻译',
            },
          ],
        },
      ],
    },
  },
};

如果你使用搜索功能，搜索框会默认是导航栏中最右边的元素。

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

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

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

NameTypeDefaultDescription
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 对象中。

接受的字段：

NameTypeDefaultDescription
themePrismThemepalenightThe Prism theme to use for light-theme code blocks.
darkThemePrismThemepalenightThe Prism theme to use for dark-theme code blocks.
defaultLanguagestringundefinedThe side of the navbar this item should appear on.
magicCommentsMagicCommentConfig[]see belowThe 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.foot 为页脚添加图标和版权声明。 图标可以放在静态文件夹中。 图标 URL 的工作方式和导航栏图标相同。

接受的字段：

NameTypeDefaultDescription

示例配置：

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

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

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

NameTypeDefaultDescription

每个 FooterItem 接受的字段为：

NameTypeDefaultDescription

多列页脚配置示例：

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 调整默认的目录样式。

NameTypeDefaultDescription
minHeadingLevelnumber2The minimum heading level shown in the table of contents. 必须介于 2 到 6 之间，并且小于等于最大值。
maxHeadingLevelnumber3Max heading level displayed in the TOC. 必须是 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