プラグイン

プラグインは、Docusaurus サイトに機能を追加するための基本的な構成要素です。各プラグインにはそれぞれの機能があります。プラグインは、プリセットを介してバンドルの一部として動作し、配布されることがあります。

プラグインの作成

プラグインは context と options の2つのパラメータを取る関数です。プラグインインスタンスオブジェクト (または promise) を返します。また、関数やモジュールとしてプラグインを作成することもできます。詳しくは、プラグインメソッドのリファレンスセクションを参照してください。

関数の定義

プラグインは、Docusaurus の設定ファイルに直接関数として含めて使用できます。

docusaurus.config.js
export default {
  // ...
  plugins: [
    async function myPlugin(context, options) {
      // ...
      return {
        name: 'my-plugin',
        async loadContent() {
          // ...
        },
        async contentLoaded({content, actions}) {
          // ...
        },
        /* 他のライフサイクルの API */
      };
    },
  ],
};

モジュールの定義

プラグインを別のファイルまたは npm パッケージを参照するモジュールパスとして使用できます。

docusaurus.config.js
export default {
  // ...
  plugins: [
    // options なし
    './my-plugin',
    // 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}) {
      /* ... */
    },
    /* その他のライフサイクル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'],
};

ここで、テーマはプラグインと同じデータを受け取りますが、テーマがそのデータをどう使って_レンダリング_するかは大きく異なることがあります。

テーマがプラグインとまったく同じライフサイクルメソッドを共有する一方、テーマの実装はその設計目標に基づいてプラグインの実装とは大きく異なることがあります。

テーマは、Docusaurusサイトのビルドを完結させるために設計されており、サイトやプラグイン、そしてテーマ自身が利用するコンポーネントを提供します。テーマもプラグインのように振る舞い、いくつかのライフサイクルメソッドを公開しますが、通常は [loadContent](../api/plugin-methods/lifecycle-apis.mdx#loadContent) を使いません。なぜなら、テーマ自身でデータを生成せず、プラグインから渡されたデータを受け取るだけだからです。また、テーマには一般的に ``src/theme\ ディレクトリがあり、多数のコンポーネントが含まれています。これらは [getThemePath](../api/plugin-methods/extend-infrastructure.mdx#getThemePath) ライフサイクルを通じてコアに認識されます。

まとめると：

テーマはプラグインと同じライフサイクルメソッドを共有しています
テーマはすべてのプラグインが実行された後に動作します
テーマは getThemePath を使用することでコンポーネントのエイリアスを追加します。

プラグインの作成​

関数の定義​

モジュールの定義​

プラグインのデザイン​

テーマのデザイン​

プラグインの作成

関数の定義

モジュールの定義

プラグインのデザイン

テーマのデザイン