登录
目录
当前位置： 首页 > 文档资料 > Docusaurus 中文文档 >

配置主题

优质
小牛编辑
115浏览
2023-12-01

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

常用配置

日间模式 - 夜间模式

classic 主题默认提供了对日间模式和夜间模式的支持，并在导航条上提供了切换开关。

通过以下配置可以自定义各模式：

docusaurus.config.js
module.exports = {
  // ...
  themeConfig: {
    // ...
    colorMode: {
      // "light" | "dark"
defaultMode: 'light', // 隐藏导航条上的切换开关 // 用于仅支持某个单一模式（即不支持模式切换） disableSwitch: false, // 是否使用 prefers-color-scheme 这一媒体查询， // 使用用户系统的偏好设置，而不是硬编码的 defaultMode respectPrefersColorScheme: false, // Dark/light 切换开关所用的图标 switchConfig: { // 夜间模式所对应的图标 darkIcon: ' ', // 应用于夜间模式图标的 CSS // React 内联样式对象 // 参见 https://reactjs.org/docs/dom-elements.html#style darkIconStyle: { marginLeft: '2px', }, // Unicode 图标（例如 '\u2600'）也能使用 // 5 个字符组成的 Unicode 需要添加花括号： '\u{1F602}' lightIcon: '\u{1F602}', lightIconStyle: { marginLeft: '1px', }, }, }, // ... }, // ... };
caution

如果开启 respectPrefersColorScheme: true，则 defaultMode 会被用户系统的偏好设置所覆盖。

如果你只想支持某一单一模式，则可能要忽略用户系统的首选项。

Meta image

你可以配置用于 meta 标签的默认图片，尤其是 og:image 和 twitter:image。

docusaurus.config.js
module.exports = {
  // ...
  themeConfig: {
    // 相对于站点的 "static" 目录。
// 不能是 SVG 图片。可以是外部 URL。 image: 'img/docusaurus.png', // ... }, };

元数据（Metadatas）

你可以配置其它 HTML 元数据（并覆盖已有的元数据）。

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

公告条

有时你想在网站上宣布一些内容。仅在这种情况下，你可以添加一个公告条。此公告条位于导航条上方，不固定（fixed）在页面顶部，用户可以将其关闭。

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', // 默认为 `#fff`。 textColor: '#091E42', // 默认为 `#000`。 isCloseable: false, // 默认为 `true`。 }, // ... }, };

i18n

请首先阅读 i18n 简介 。

待翻译文件所在位置

  • Base path: website/i18n/<locale>/docusaurus-theme-<themeName>
  • Multi-instance path: N/A
  • JSON files: extracted with docusaurus write-translations
  • Markdown files: `N/A

文件系统结构示例

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

Hooks

useThemeContext

用于访问主题的上下文（context）的 React hook。该上下文（context）包含了用于设置日间或夜间模式的函数以及指示当前正在使用哪种模式的函数。

用法示例：

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

导航条

导航条上的标题和 logo

你可以通过 themeConfig.navbar 为导航条添加 logo 和标题。logo 可以被放置在 static 目录 中。默认情况下，logo 所对应的 URL 设置为网站的根地址。尽管可以为 logo 指定一个 URL，但如果时外部链接的话，则将在新标签页中打开。此外，你可以覆盖 logo 所对应链接的 target 属性，如果你将文档网站托管在主网站的子目录下，这个属性就派上用场了，这种情况下，你肯定不希望 logo 所链接的主站在新标签页中打开。

为了改善对夜间模式的支持，你还可以为此模式设置一个专用的 logo。

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/', // 默认值为 `siteConfig.baseUrl`。 target: '_self', // By default, this value is calculated based on the `href` attribute (the external link will open in a new tab, all others in the current one). }, }, // ... }, };

导航条上的元素

你可以通过 themeConfig.navbar.items 为导航条添加不同的元素。

默认情况下，导航条上的元素是普通的（内部或外部）链接。

docusaurus.config.js
module.exports = {
  // ...
  themeConfig: {
    navbar: {
      items: [
{ // Client-side routing, used for navigating within the website. // The baseUrl will be automatically prepended to this value. to: 'docs/introduction', // A full-page navigation, used for navigating outside of the website. // You should only use either `to` or `href`. href: 'https://www.facebook.com', // Prepends the baseUrl to href values. prependBaseUrlToHref: true, // The string to be shown. label: 'Introduction', // Left or right side of the navbar. position: 'left', // or 'right' // To apply the active class styling on all // routes starting with this path. // This usually isn't necessary activeBasePath: 'docs', // Alternative to activeBasePath if required. activeBaseRegex: 'docs/(next|v8)', // Custom CSS class (for styling any item). className: '', }, // ... other items ], }, // ... }, };

React Router should automatically apply active link styling to links, but you can use activeBasePath in edge cases. For cases in which a link should be active on several different paths (such as when you have multiple doc folders under the same sidebar), you can use activeBaseRegex. activeBaseRegex is a more flexible alternative to activeBasePath and takes precedence over it -- Docusaurus parses it into a regular expression that is tested against the current URL.

出站（外部）链接将被自动添加 target="_blank" rel="noopener noreferrer" 属性。

Navbar dropdown

Navbar items can also be dropdown items by specifying the items, an inner array of navbar items.

docusaurus.config.js
module.exports = {
  // ...
  themeConfig: {
    navbar: {
      items: [
        {
          label: 'Community',
          position: 'left', // or 'right'
          items: [
{ label: 'Facebook', href: '...', }, { label: 'GitHub', href: '...', }, // ... more items ], }, ], }, // ... }, };

导航条上的文档链接

如果要链接到某个特定的文档，则这种特殊的导航条元素将根据你所提供的 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', }, ], }, }, };

Navbar docs version dropdown

If you use docs with versioning, this special navbar item type that will render a dropdown with all your site's available versions.

The user will be able to switch from one version to another, while staying on the same doc (as long as the doc id is constant across versions).

docusaurus.config.js
module.exports = {
  themeConfig: {
    navbar: {
      items: [
        {
type: 'docsVersionDropdown', //// Optional position: 'left', // Add additional dropdown items at the beginning/end of the dropdown. dropdownItemsBefore: [], dropdownItemsAfter: [{to: '/versions', label: 'All versions'}], // Do not add the link active class when browsing docs. dropdownActiveClassDisabled: true, docsPluginId: 'default', }, ], }, }, };

Navbar docs version

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.

docusaurus.config.js
module.exports = {
  themeConfig: {
    navbar: {
      items: [
        {
type: 'docsVersion', //// Optional position: 'left', to: '/path', // by default, link to active/latest version label: 'label', // by default, show active/latest version label docsPluginId: 'default', }, ], }, }, };

Navbar locale dropdown

If you use the i18n feature, this special navbar item type will render a dropdown with all your site's available locales.

The user will be able to switch from one locale to another, while staying on the same page.

docusaurus.config.js
module.exports = {
  themeConfig: {
    navbar: {
      items: [
        {
type: 'localeDropdown', //// Optional position: 'left', // Add additional dropdown items at the beginning/end of the dropdown. dropdownItemsBefore: [], dropdownItemsAfter: [ { to: 'https://my-site.com/help-us-translate', label: 'Help us translate', }, ], }, ], }, }, };

导航条上搜索框

如果你使用了 搜索功能，则搜索框将放置于导航条的最右侧。

不过，对于这一特殊的导航条元素，你可以更改它的默认位置。

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

自动隐藏的粘性导航条

你可以开启这个酷炫的 UI 功能，当用户开始向下滚动页面时自动隐藏导航条，当用户向上滚动页面时则显示导航条。

docusaurus.config.js
module.exports = {
  // ...
  themeConfig: {
    navbar: {
      hideOnScroll: true,
}, // ... }, };

导航条的样式

You can set the static Navbar style without disabling the theme switching ability. The selected style will always apply no matter which theme user have selected.

当前，有两种可用的样式：dark 和 primary （基于 --ifm-color-primary 颜色）。你可以在 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 语法，则可能需要为夜间模式的语法高亮主题指定一个不同的背景色。请参阅 该指导文档。

默认编程语言

如果在三个起始反引号（例如 ```）之后未标示本代码块所使用的编程语言，则该代码块被设置为默认的编程语言。请注意，必须设置有效的 编程语言名称 ，例如：

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

页脚

你可以通过 themeConfig.footer 向页脚添加 logo 和版权声明。logo 可以放置于 static 目录 中。此处的 logo 所对应的 URL 与导航条上的 logo 所对应的 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: [
      {
// Label of the section of these links title: 'Docs', items: [ { // Label of the link label: 'Style Guide', // Client-side routing, used for navigating within the website. // The baseUrl will be automatically prepended to this value. to: 'docs/', }, { label: 'Second Doc', to: 'docs/doc2/', }, ], }, { title: 'Community', items: [ { label: 'Stack Overflow', // A full-page navigation, used for navigating outside of the website. href: 'https://stackoverflow.com/questions/tagged/docusaurus', }, { label: 'Discord', href: 'https://discordapp.com/invite/docusaurus', }, { label: 'Twitter', href: 'https://twitter.com/docusaurus', }, { //Renders the html pass-through instead of a simple link 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> `, }, ], }, ], }, };
免责声明： 以上内容版权归原作者所有，如有侵犯您的原创版权请告知，我们将尽快删除相关内容。感谢每一位辛勤著写的作者，感谢每一位的分享。
@小牛知识库 xnip.cn