版本：3.5.2

使用外掛

Docusaurus 內建核心本身不提供任何功能。所有功能均委派給個別外掛：文件功能由文件外掛提供；部落格功能由部落格外掛提供；或個別頁面由頁面外掛提供。若無安裝任何外掛，網站則不會有任何路由。

雖然您可能不必逐一安裝常見的外掛，但它們可以以預設設定組形式打包成一個組件。對於大多數使用者而言，外掛是透過預設設定組設定檔設定的。

我們會持續維護一份官方外掛清單，而社群也製作了一些非官方外掛。如果您想新增任何功能，如自動產生文件頁面、執行自訂程式碼、整合其他服務……請務必查看清單，或許有人已為您實作！

若您精力充沛，您也可以閱讀外掛指南或外掛方法參考以了解如何自己製作外掛。

安裝外掛

外掛通常為 npm 套件，因此您可以使用 npm 安裝外掛，就像安裝其他 npm 套件一樣。

npm
Yarn
pnpm

npm install --save docusaurus-plugin-name

yarn add docusaurus-plugin-name

pnpm add docusaurus-plugin-name

然後將其加入網站的 docusaurus.config.js 的 plugins 選項中

docusaurus.config.js
export default {
  // ...
  plugins: ['@docusaurus/plugin-content-pages'],
};

Docusaurus 也可以從您的本機目錄載入外掛，方式類似於以下內容

docusaurus.config.js
export default {
  // ...
  plugins: ['./src/plugins/docusaurus-local-plugin'],
};

路徑應該是絕對路徑或以設定檔為基準的相對路徑。

設定外掛

對於最基本的外掛使用方式，您只需提供外掛名稱或外掛路徑。

然而，外掛可以透過在外掛名稱和選項物件 (object) 外側加上兩元組，並放置在 config 內部來設定選項。這種風格通常稱為「Babel 風格」。

docusaurus.config.js
export default {
  // ...
  plugins: [
    [
      '@docusaurus/plugin-xxx',
      {
        /* options */
      },
    ],
  ],
};

範例

docusaurus.config.js
export default {
  plugins: [
    // Basic usage.
    '@docusaurus/plugin-debug',

    // With options object (babel style)
    [
      '@docusaurus/plugin-sitemap',
      {
        changefreq: 'weekly',
      },
    ],
  ],
};

多個外掛實例和外掛 ID

所有 Docusaurus 內容外掛都可以支援多個外掛實例。例如，同時擁有多個文件外掛實例或多個部落格可能會有用處。每個外掛實例都必須指定一個唯一的 ID，預設的外掛 ID 是 default。

docusaurus.config.js
export default {
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'docs-1',
        // other options
      },
    ],
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'docs-2',
        // other options
      },
    ],
  ],
};

註記

最多只能有一個外掛實例是「預設外掛實例」，方法是省略 id 屬性或使用 id: 'default'。

使用佈景主題

載入佈景主題的方式與外掛完全相同。從使用者的角度來看，在安裝和設定外掛時，themes 和 plugins 的項目在載入上有相同的效果。唯一的差異在於佈景主題是在外掛載入之後載入，而且佈景主題可以覆寫外掛的預設佈景主題元件。

小訣竅

themes 和 plugins 選項會導致不同的簡寫解決方案，所以如果您想要利用簡寫，一定要使用正確的條目！

docusaurus.config.js
export default {
  // ...
  themes: ['@docusaurus/theme-classic', '@docusaurus/theme-live-codeblock'],
};

使用預設值

預設值是外掛和主題的組合。例如，系統並不會讓您依序在組態檔中註冊和設定 @docusaurus/plugin-content-docs、@docusaurus/plugin-content-blog，等等。我們有 @docusaurus/preset-classic 預設值讓您可以在一處集中設定這些項目。

`@docusaurus/preset-classic`

使用 create-docusaurus 建立新的 Docusaurus 網站時，預設會提供經典預設值。它包含下列主題和外掛

經典預設值會將每個選項條目中繼到其對應的外掛/主題。

docusaurus.config.js
export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        // Debug defaults to true in dev, false in prod
        debug: undefined,
        // Will be passed to @docusaurus/theme-classic.
        theme: {
          customCss: ['./src/css/custom.css'],
        },
        // Will be passed to @docusaurus/plugin-content-docs (false to disable)
        docs: {},
        // Will be passed to @docusaurus/plugin-content-blog (false to disable)
        blog: {},
        // Will be passed to @docusaurus/plugin-content-pages (false to disable)
        pages: {},
        // Will be passed to @docusaurus/plugin-sitemap (false to disable)
        sitemap: {},
        // Will be passed to @docusaurus/plugin-google-gtag (only enabled when explicitly specified)
        gtag: {},
        // Will be passed to @docusaurus/plugin-google-tag-manager (only enabled when explicitly specified)
        googleTagManager: {},
        // DEPRECATED: Will be passed to @docusaurus/plugin-google-analytics (only enabled when explicitly specified)
        googleAnalytics: {},
      },
    ],
  ],
};

安裝預設值

預設值通常是個 npm 套件，因此您使用 npm 像安裝其他 npm 套件一樣安裝它。

npm
Yarn
pnpm

npm install --save @docusaurus/preset-classic

yarn add @docusaurus/preset-classic

pnpm add @docusaurus/preset-classic

然後，將它加入您網站的 docusaurus.config.js 的 presets 選項中

docusaurus.config.js
export default {
  // ...
  presets: ['@docusaurus/preset-classic'],
};

預設值路徑可以相對於組態檔

docusaurus.config.js
export default {
  // ...
  presets: ['./src/presets/docusaurus-local-preset'],
};

建立預設值

預設值是一個函式，它的形狀與外掛建構函式相同。它應該傳回一個 { plugins: PluginConfig[], themes: PluginConfig[] } 物件，與它們在網站設定中被接受的方式相同。例如，您可以設定一個預設值，其中包括下列主題和外掛

src/presets/docusaurus-preset-multi-docs.js
export default function preset(context, opts = {}) {
  return {
    themes: [['docusaurus-theme-awesome', opts.theme]],
    plugins: [
      // Using three docs plugins at the same time!
      // Assigning a unique ID for each without asking the user to do it
      ['@docusaurus/plugin-content-docs', {...opts.docs1, id: 'docs1'}],
      ['@docusaurus/plugin-content-docs', {...opts.docs2, id: 'docs2'}],
      ['@docusaurus/plugin-content-docs', {...opts.docs3, id: 'docs3'}],
    ],
  };
}

然後，您可以在 Docusaurus 設定中設定預設值

docusaurus.config.js
export default {
  presets: [
    [
      './src/presets/docusaurus-preset-multi-docs.js',
      {
        theme: {hello: 'world'},
        docs1: {path: '/docs'},
        docs2: {path: '/community'},
        docs3: {path: '/api'},
      },
    ],
  ],
};

這等於執行

docusaurus.config.js
export default {
  themes: [['docusaurus-theme-awesome', {hello: 'world'}]],
  plugins: [
    ['@docusaurus/plugin-content-docs', {id: 'docs1', path: '/docs'}],
    ['@docusaurus/plugin-content-docs', {id: 'docs2', path: '/community'}],
    ['@docusaurus/plugin-content-docs', {id: 'docs3', path: '/api'}],
  ],
};

當某些外掛和佈景主題預計要一起使用時，這類功能會特別好用。您甚至可以連結它們的選項，例如將一個選項傳遞給多個外掛。

模組簡寫符

Docusaurus 支援外掛、佈景主題和預設值簡寫符。當它看到外掛/佈景主題/預設值名稱時，它會依序嘗試載入下列其中一項

[name]（例如 content-docs）
@docusaurus/[moduleType]-[name]（例如 @docusaurus/plugin-content-docs）
docusaurus-[moduleType]-[name]（例如 docusaurus-plugin-content-docs）

其中 moduleType 是 'preset'、'theme' 或 'plugin' 之一，視宣告模組名稱的欄位而定。最先找到並成功載入的模組名稱就是所載入的模組。

如果名稱是範圍化（以 @ 開頭），則會先以第一個斜線將名稱分割成範圍和套件名稱

@scope
^----^
 scope  (no name!)

@scope/awesome
^----^ ^-----^
 scope   name

@scope/awesome/main
^----^ ^----------^
 scope     name

如果沒有名稱（例如 @jquery），則會載入 [scope]/docusaurus-[moduleType]（也就是 @jquery/docusaurus-plugin）。否則，則會嘗試載入以下內容

[scope]/[name]（例如 @jquery/content-docs）
[scope]/docusaurus-[moduleType]-[name]（例如 @jquery/docusaurus-plugin-content-docs）

以下是一些範例，它們適用於在 plugins 欄位中註冊的外掛。請注意，與ESLint或Babel不同的是，後兩者強制採用一致的外掛命名慣例，而 Docusaurus 允許更大的命名自由度，因此解析結果並不是確定的，而是遵循上述優先順序。

宣告	可能解析為
`awesome`	`docusaurus-plugin-awesome`
`sitemap`	`@docusaurus/plugin-sitemap`
`@my-company`	`@my-company/docusaurus-plugin`（唯一可能解析的結果！）
`@my-company/awesome`	`@my-company/docusaurus-plugin-awesome`
`@my-company/awesome/web`	`@my-company/docusaurus-plugin-awesome/web`

安裝外掛​

設定外掛​

多個外掛實例和外掛 ID​

使用佈景主題​

使用預設值​

@docusaurus/preset-classic​

安裝預設值​

建立預設值​

模組簡寫符​