跳至主要內容
版本：3.5.2

主題設定

此設定套用於所有 主要主題。

常見​

色彩模式​

經典主題預設提供淺色和深色模式，並提供給使用者在導覽列上切換。

可以在 colorMode 物件內自訂色彩模式支援。

接受的欄位

名稱類型預設值說明
defaultMode'light' | 'dark''light'使用者第一次造訪網站時的色彩模式。
disableSwitch布林值false隱藏導覽列中的切換開關。如果你想支援單一色彩模式的話會很有用。
respectPrefersColorScheme布林值false是否使用 prefers-color-scheme 媒體查詢，採用使用者系統喜好設定，而非編碼寫死的 defaultMode。

範例設定

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

使用 `respectPrefersColorScheme: true`，使用者系統偏好就能覆寫 `defaultMode`。

如果你只想支援一種色彩模式，可能會想忽略使用者的系統偏好。

Meta 圖片​

你可以為你 meta 標籤，尤其是 `og:image` 和 `twitter:image`，設定預設圖片。

接受的欄位

名稱類型預設值說明
圖片字串未定義網站的 meta 圖片 URL。會相對於你網站的「static」目錄。不能是 SVG。也可以是外部 URL。

範例設定

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

元資料​

你可以設定其他 HTML 元資料（並且覆寫現有元資料）。

接受的欄位

名稱類型預設值說明
元資料Metadata[][]任何欄位都會直接傳遞給 `<meta />` 標籤。可能的欄位包含 `id`、`name`、`property`、`content`、`itemprop` 等。

範例設定

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

公告欄​

有時候你會想在你的網站上公告一些事情。有公告欄就能輕鬆公告。這是個非固定的面板，並可以放置在導覽列上方，而且允許關閉。所有設定都在 `announcementBar` 物件中。

接受的欄位

名稱類型預設值說明
ID字串'announcement-bar'任何能夠識別這則訊息的值。
內容字串''公告的文字內容。會內插 HTML。
背景色字串'#fff'整個欄位的背景色。
文字顏色字串'#000'公告文字的顏色。
可關閉布林值true這個公告可否透過「×」按鈕關閉。

範例設定

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.dev.org.tw/',
        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 更為靈活的替代品，且優先於 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://127.0.0.1',
          label: 'Introduction',
          // Only one of "label" or "html" should be used
          // html: '<b>Introduction</b>'
          position: 'left',
          activeBaseRegex: 'docs/(next|v8)',
          target: '_blank',
        },
      ],
    },
  },
};

類型為 下拉選單 的導覽列項目有額外的 項目 欄位，它是導覽列項目的內部陣列。

導覽列下拉選單項目只接受下列「類似連結」的項目類型

請注意，下拉選單基本項目也是可點選的連結，因此這個項目可以接收平面導覽列連結的任何屬性。

接受的欄位

名稱類型預設值說明

範例設定

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'dropdown',
          label: 'Community',
          position: 'left',
          items: [
            {
              label: 'Facebook',
              href: 'https://127.0.0.1',
            },
            {
              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',
    },
  },
};

CodeBlock​

Docusaurus 使用 Prism React 渲染器 來突顯程式碼區塊。所有設定都在 prism 物件中。

接受的欄位

名稱類型預設值說明
themePrismThemepalenight用於淺色主題程式碼區塊的 Prism 主題。
darkThemePrismThemepalenight用於深色主題程式碼區塊的 Prism 主題。
defaultLanguage字串未定義未宣告任何明確語言時，用於程式碼區塊的預設語言。
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 將 logo 和版權加入頁尾。Logo 可以放在靜態資料夾中。Logo URL 運作方式與導覽列 Logo 相同。

接受的欄位

名稱類型預設值說明

範例設定

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 調整預設目錄。

名稱類型預設值說明
minHeadingLevel數字2顯示於目錄中的最小標題層級。必須介於 2 到 6 之間，且低於或等於最大值。
maxHeadingLevel數字3顯示於目錄中的最大標題層級。應為 2 到 6 之間的整數。

範例設定

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

Hooks​

useColorMode​

A 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]
  • 多個執行個體路徑：無
  • JSON 檔案：使用docusaurus write-translations 萃取
  • Markdown 檔案：無

範例檔案系統結構​

website/i18n/[locale]/docusaurus-theme-classic
│
│ # translations for the theme
├── navbar.json
└── footer.json
編輯此頁
最後更新於 更新，作者為 Sébastien Lorber