跳至主要内容
版本: 3.5.2

主题配置

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

通用​

颜色模式​

经典主题默认提供亮模式和暗模式支持，用户可以使用导航栏切换。

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

接受的字段

名称类型默认值描述
defaultMode'light' | 'dark''light'用户首次访问网站时的颜色模式。
disableSwitchbooleanfalse隐藏导航栏中的切换按钮。如果您想支持单一颜色模式，此选项非常有用。
respectPrefersColorSchemebooleanfalse是否使用 prefers-color-scheme 媒体查询，使用用户的系统偏好，而不是硬编码的 defaultMode。

示例配置

docusaurus.config.js
export default {
  themeConfig: {
    colorMode: {
      defaultMode: 'light',
      disableSwitch: false,
      respectPrefersColorScheme: false,
    },
  },
};
警告

使用 respectPrefersColorScheme: true 时，defaultMode 会被用户的系统偏好覆盖。

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

元图像​

您可以配置一个默认图像，该图像将用于您的元标记，特别是 og:image 和 twitter:image。

接受的字段

名称类型默认值描述
imagestringundefined网站的元图像 URL。相对于网站的“静态”目录。不能是 SVG。也可以是外部 URL。

示例配置

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

元数据​

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

接受的字段

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

示例配置

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

公告栏​

有时您希望在网站上宣布一些内容。在这种情况下，您可以添加一个公告栏。这是一个非固定且可选的可以关闭的，位于导航栏上方的面板。所有配置都在 announcementBar 对象中。

接受的字段

名称类型默认值描述
idstring'announcement-bar'任何标识此消息的值。
contentstring''公告的文本内容。将插入 HTML。
backgroundColorstring'#fff'整个栏的背景颜色。
textColorstring'#000'公告文本颜色。
isCloseablebooleantrue此公告是否可以通过“×”按钮关闭。

示例配置

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 核心内容插件提供了额外的主题配置选项。

文档​

名称类型默认值描述

示例配置

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

博客​

名称类型默认值描述

示例配置

docusaurus.config.js
export default {
  themeConfig: {
    blog: {
      sidebar: {
        groupByYear: true,
      },
    },
  },
};

接受的字段

名称类型默认值描述

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

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

接受的字段

名称类型默认值描述

示例配置

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.org.cn/',
        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" 属性。

接受的字段

名称类型默认值描述
注意

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

示例配置

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

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

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

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

接受的字段

名称类型默认值描述

示例配置

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

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

接受的字段

名称类型默认值描述

示例配置

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

您可以将导航栏项链接到给定侧边栏的第一个文档链接（可以是文档链接或生成的类别索引），而无需硬编码文档 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', // The navbar item will be linking to this doc
    'docusaurus-core',
    {
      type: 'autogenerated',
      dirName: 'api',
    },
  ],
};

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

用户可以从一个版本切换到另一个版本，同时保留在同一个文档上（只要文档 ID 在不同版本中保持一致）。

接受的字段

名称类型默认值描述

示例配置

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

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

接受的字段

名称类型默认值描述

示例配置

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

如果您使用 i18n 功能，此特殊的导航栏项类型将呈现一个包含您网站所有可用语言环境的下拉菜单。

用户可以从一个语言环境切换到另一个语言环境，同时保留在同一页面上。

接受的字段

名称类型默认值描述

示例配置

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

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

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

名称类型默认值描述
docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'search',
          position: 'right',
        },
      ],
    },
  },
};

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

名称类型默认值描述
docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'html',
          position: 'right',
          value: '<button>Give feedback</button>',
        },
      ],
    },
  },
};

自动隐藏粘性导航栏​

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

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      hideOnScroll: true,
    },
  },
};

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

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

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      style: 'primary',
    },
  },
};

代码块​

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

接受的字段

名称类型默认值描述
themePrismThemepalenight用于浅色主题代码块的 Prism 主题。
darkThemePrismThemepalenight用于深色主题代码块的 Prism 主题。
defaultLanguagestringundefined用于未声明任何显式语言的代码块的默认语言。
magicCommentsMagicCommentConfig[]见下文魔法注释 的列表。
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 的工作方式与导航栏徽标相同。

接受的字段

名称类型默认值描述

示例配置

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

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

多列页脚链接具有一个 title 和一个 FooterItem 列表，用于每一列。

名称类型默认值描述

每个 FooterItem 的接受字段

名称类型默认值描述

多列配置示例

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: '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
export default {
  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 调整默认目录。

名称类型默认值描述
minHeadingLevelnumber2目录中显示的最小标题级别。必须介于 2 到 6 之间，并且小于或等于最大值。
maxHeadingLevelnumber3TOC 中显示的最大标题级别。应为介于 2 到 6 之间的整数。

示例配置

docusaurus.config.js
export default {
  themeConfig: {
    tableOfContents: {
      minHeadingLevel: 2,
      maxHeadingLevel: 5,
    },
  },
};

Hooks​

useColorMode​

一个用于访问颜色上下文的 React Hook。此上下文包含用于设置浅色和深色模式的函数，并公开一个布尔变量，指示当前使用哪个模式。

用法示例

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 文件：使用 docusaurus write-translations 提取。
  • Markdown 文件：N/A

文件系统结构示例​

website/i18n/[locale]/docusaurus-theme-classic
│
│ # translations for the theme
├── navbar.json
└── footer.json
编辑此页面
上次更新于 由 Sébastien Lorber 更新