跳转至主内容
Version: 2.0.0-beta.3

主题配置

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

通用#

颜色模式 - 暗色模式#

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

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

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 文件: `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: [        {          // 客户端路由，用于在网站内导航。          // BaseUrl 将自动添加到这个值。          to: 'docs/introduction',          // 全页导航, 用于导航外部.          // 您只能使用 `to` 或 `href` 。          href: 'https://www.facebook.com',          // 将 baseUrl 置于href 值中。          pendBaseUrlToHref：true，          // 要显示的字符串。          label: 'Introduction',          // 导航栏的左侧或右侧          position: 'left', // 或 'right'          // 应用于所有激活样式上          // 路径开始于此          // 通常不必要          activeBasePath: 'docs',          // 如果需要，代替  activeBasePath.          activeBaseRegex: 'docs/(next|v8)',          //自定义CSS类 (用于任何项目样式).          className: '',        },        // ... 其他项目      ],      //高亮结束    },    // ...  },};

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

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

导航栏下拉列表#

导航栏项目也可以通过指定 item，作为导航栏项目的内部数组。

docusaurus.config.js
module.exports = {  // ...  themeConfig: {    navbar: {      items: [        {          label: 'Community',          position: 'left', // 或 'right'          items: [            {              label: 'Facebook',              href: '...',            },            {              label: 'GitHub',              href: '...',            },            // ... 更多项目          ],        },      ],    },    // ...  },};

导航栏 文档 链接#

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

docusaurus.config.js
module.exports = {  themeConfig: {    navbar: {      items: [        // 高亮开始        {          type: 'doc',          docId: 'introduction',
          //// 可选择          position: 'left',          label: 'Docs',          activeSidebarClassName: 'navbar__link--active',          docsPluginId: 'default',        },        // 高亮结束      ],    },  },};

导航栏 文档版本下拉列表#

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

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

docusaurus.config.js
module.exports = {  themeConfig: {    navbar: {      items: [        {          type: 'docsVersionDropdown',
          //// 可选择          position: 'left',          // 在开头或结尾加入额外的下拉项          dropdownloaditemBefore: [],          dropdownitemsAfter: [{to: '/versions', 标签: '所有版本'}],          // 在浏览文档时不添加链接活动类。          dropdownActiveClassDisabled: true,          docsPluginId: 'default',        },      ],    },  },};

导航栏文档版本#

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

docusaurus.config.js
module.exports = {  themeConfig: {    navbar: {      items: [        // 高亮开始        {          type: 'docsVersion',
          //// 可选择          position: 'left',          to: '/path', // 默认, 链接到激活/最新版本          label: 'label', // 默认, 展示激活/最新版本标签          docsPluginId: 'default',        },        // 高亮结束      ],    },  },};

导航栏区域下拉列表#

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

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

docusaurus.config.js
module.exports = {  themeConfig: {    navbar: {      items: [        {          type: 'localeDropdown',
          //// 可选          position: 'left',          //在下拉菜单的开始/结尾处添加其他下拉菜单项          dropdownItemsBefore: [],          dropdownItemsAfter: [            {              to: 'https://my-site.com/help-us-translate',              label: 'Help us translate',            },          ],        },      ],    },  },};

导航栏搜索#

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

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

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