版本：3.5.2

外掛

外掛是 Docusaurus 網站中功能的建構區塊。每個外掛都會處理自己的個別功能。外掛可以透過預設值作為套件的一部分來運作和發布。

建立外掛

外掛是一種函數，它帶有兩個參數：context 和 options。它傳回外掛實體物件（或承諾）。你可以將外掛建立為函數或模組。欲了解更多資訊，請參閱外掛方法參考區段。

函數定義

你可以直接將外掛作為函數包含在 Docusaurus 的組態檔案中

docusaurus.config.js
export default {
  // ...
  plugins: [
    async function myPlugin(context, options) {
      // ...
      return {
        name: 'my-plugin',
        async loadContent() {
          // ...
        },
        async contentLoaded({content, actions}) {
          // ...
        },
        /* other lifecycle API */
      };
    },
  ],
};

模組定義

你可以將外掛作為模組路徑使用，它會參考一個獨立的檔案或 npm 套件

docusaurus.config.js
export default {
  // ...
  plugins: [
    // without options:
    './my-plugin',
    // or with options:
    ['./my-plugin', options],
  ],
};

然後在資料夾 my-plugin 中，你可以建立類似以下內容的 index.js

my-plugin/index.js
export default async function myPlugin(context, options) {
  // ...
  return {
    name: 'my-plugin',
    async loadContent() {
      /* ... */
    },
    async contentLoaded({content, actions}) {
      /* ... */
    },
    /* other lifecycle API */
  };
}

你可以使用除錯外掛的元資料面板來檢視你網站安裝的所有外掛。

外掛有幾種類型

package：你安裝的外接套件
project：你在你的專案中建立的外掛，以本機檔案路徑的形式提供給 Docusaurus
local：使用函數定義建立的外掛
synthetic：Docusaurus 在內部建立的一個「假外掛」，因此我們可以利用我們的模組化架構，並且讓核心不要做太多特殊工作。你不會在元資料中看到它，因為它是一個實作細節。

你可以使用 useDocusaurusContext().siteMetadata.pluginVersions 在用戶端存取它們。

外掛設計

Docusaurus 的外掛系統實作提供我們一種便利的方式，讓我們可以導入網站的生命週期，來修改在開發/建置期間發生的任何事情，這包括（但不限於）擴充 webpack 設定檔、修改載入的資料，以及建立要在網頁中使用的元件。

佈景主題設計

當外掛載入其內容時，資料會透過 createData + addRoute 類似的動作或 setGlobalData 提供給用戶端。這個資料必須序列化為純文字，因為外掛和佈景主題在不同的環境執行。資料抵達用戶端後，接下來的部分對於 React 開發人員來說會很熟悉：資料會沿著元件傳遞，元件會與 Webpack 捆綁在一起，並透過 ReactDOM.render 呈現到視窗中...

佈景主題提供 UI 元件，以呈現內容。多數內容外掛需要與佈景主題配對，才能實際有用。UI 是與資料結構分離的獨立層，這使得更換設計變得容易。

例如，Docusaurus 部落格可能會包含部落格外掛和部落格佈景主題。

注意

這是一個虛構的範例：實際上，@docusaurus/theme-classic 為文件、部落格和佈局提供佈景主題。

docusaurus.config.js
export default {
  themes: ['theme-blog'],
  plugins: ['plugin-content-blog'],
};

而且如果你想使用 Bootstrap 造型，你可以使用 theme-blog-bootstrap（另一個虛構的不存在佈景主題）來切換佈景主題

docusaurus.config.js
export default {
  themes: ['theme-blog-bootstrap'],
  plugins: ['plugin-content-blog'],
};

現在，儘管主題會從插件接收相同資料，但主題選擇以 UI 呈現資料的方式可能截然不同。

儘管主題與插件共用完全相同的生命週期方法，但根據主題的設計目標，主題的實作看起來可能與插件的實作大不相同。

主題設計用於完成 Docusaurus 網站的建置，並提供網站、插件和主題本身使用的元件。主題仍然像一個插件，並公開一些生命週期方法，但它們很可能不會使用 loadContent，因為它們只接收來自插件的資料，但本身不會產生資料；主題通常也伴隨著一個充滿元件的 src/theme 目錄，這些元件會透過 getThemePath 生命週期讓核心程式知道。

總結如下

主題與插件共用相同生命週期方法
主題會在所有現有插件之後執行
主題透過提供 getThemePath 來新增元件別名。

建立外掛​

函數定義​

模組定義​

外掛設計​

佈景主題設計​

建立外掛

函數定義

模組定義

外掛設計

佈景主題設計