プラグインの使用

Docusaurus コア自体は、独自の機能を提供していません。 すべての機能は個々のプラグインに委任されます。ドキュメント機能はドキュメントプラグインによって提供され、ブログ機能はブログプラグインによって提供され、個々のページはページプラグインによって提供されます。プラグインがインストールされていない場合、サイトにはルートが含まれません。

ただし、一般的なプラグインを1つずつインストールする必要はありません。プリセットにバンドルとして配布できます。ほとんどのユーザーにとって、プラグインはプリセット設定を通じて設定されます。

私たちは公式プラグインのリストを管理していますが、コミュニティも非公式プラグインを作成しています。ドキュメントページの自動生成、カスタムスクリプトの実行、他のサービスとの統合など、機能を追加したい場合は、リストを確認してください。誰かがすでに実装しているかもしれません！

意欲的な方は、プラグインガイドまたはプラグインメソッドリファレンスを読んで、独自のプラグインを作成する方法を学ぶこともできます。

プラグインのインストール

プラグインは通常npmパッケージであるため、npmを使用して他のnpmパッケージと同様にインストールします。

npm

npm install --save docusaurus-plugin-name

Yarn

yarn add docusaurus-plugin-name

pnpm

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'],
};

パスは絶対パスまたは設定ファイルからの相対パスである必要があります。

プラグインの設定

プラグインの最も基本的な使用方法では、プラグイン名またはプラグインへのパスのみを提供できます。

ただし、プラグインには、設定内で名前とオプションオブジェクトを2つのメンバーを持つタプルで囲むことによって、オプションを指定できます。このスタイルは通常、「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'` を使用することにより、最大で1つのプラグインインスタンスを「デフォルトプラグインインスタンス」にすることができます。

テーマの使用

テーマはプラグインとまったく同じ方法でロードされます。コンシューマーの観点からは、プラグインのインストールと設定において、 `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` プリセットを使用すると、1か所でまとめて設定できます。

`@docusaurus/preset-classic`

classicプリセットは、`create-docusaurus`で作成された新しいDocusaurus Webサイトにデフォルトで付属しています。次のテーマとプラグインが含まれています。

• @docusaurus/theme-classic
• @docusaurus/theme-search-algolia
• @docusaurus/plugin-content-docs
• @docusaurus/plugin-content-blog
• @docusaurus/plugin-content-pages
• @docusaurus/plugin-debug
• @docusaurus/plugin-google-gtag
• @docusaurus/plugin-google-tag-manager
• `@docusaurus/plugin-google-analytics` (**非推奨**)
• @docusaurus/plugin-sitemap

classicプリセットは、各オプションエントリをそれぞれのプラグイン/テーマにリレーします。

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

npm install --save @docusaurus/preset-classic

Yarn

yarn add @docusaurus/preset-classic

pnpm

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'}],
  ],
};

これは、一部のプラグインとテーマを一緒に使用する必要がある場合に特に役立ちます。たとえば、1つのオプションを複数のプラグインに渡すなど、オプションをリンクすることもできます。

モジュール省略記法

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