バージョン: 3.5.2

ドキュメントの複数インスタンス

@docusaurus/plugin-content-docs プラグインは、複数インスタンスをサポートできます。

注意

この機能は、バージョン付きドキュメントでのみ役立ちます。このページを読む前に、ドキュメントのバージョニングに慣れておくことをお勧めします。単に複数のサイドバーが必要な場合は、1つのプラグイン内で実現できます。

ユースケース

Docusaurus サイトで、2 つ (またはそれ以上) の異なるドキュメントセットをホストしたい場合があります。

これらのドキュメントには、異なるバージョニング/リリースライフサイクルがある場合もあります。

モバイル SDK ドキュメント

クロスプラットフォームのモバイル SDK を構築する場合、2 つのドキュメントが必要になる場合があります。

Android SDK ドキュメント (v1.0, v1.1)
iOS SDK ドキュメント (v1.0, v2.0)

この場合、モバイル SDK ドキュメントごとに異なる docs プラグインインスタンスを使用できます。

警告

各ドキュメントインスタンスが非常に大きい場合は、代わりに 2 つの異なる Docusaurus サイトを作成する必要があります。

誰かが iOS ドキュメントを編集した場合、変更されていない Android ドキュメント全体を含め、すべてをリビルドするのは本当に役立ちますか？

バージョン付きドキュメントとバージョンなしドキュメント

ドキュメントの中にはバージョン管理したいものもあれば、他のドキュメントはより「グローバル」で、バージョン管理するのは無意味だと感じるものもあるでしょう。

Docusaurus のウェブサイト自体でこのパターンを使用しています。

/docs/* セクションはバージョン管理されています。
/community/* セクションはバージョン管理されていません。

セットアップ

2 つのドキュメントがあると仮定します。

製品: 製品に関するバージョン付きドキュメント
コミュニティ: 製品周辺のコミュニティに関するバージョンなしドキュメント

この場合、サイト構成で同じプラグインを 2 回使用する必要があります。

警告

@docusaurus/preset-classic には、docs プラグインインスタンスがすでに含まれています。

プリセットを使用する場合

docusaurus.config.js
export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          // id: 'product', // omitted => default instance
          path: 'product',
          routeBasePath: 'product',
          sidebarPath: './sidebarsProduct.js',
          // ... other options
        },
      },
    ],
  ],
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'community',
        path: 'community',
        routeBasePath: 'community',
        sidebarPath: './sidebarsCommunity.js',
        // ... other options
      },
    ],
  ],
};

プリセットを使用しない場合

docusaurus.config.js
export default {
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        // id: 'product', // omitted => default instance
        path: 'product',
        routeBasePath: 'product',
        sidebarPath: './sidebarsProduct.js',
        // ... other options
      },
    ],
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'community',
        path: 'community',
        routeBasePath: 'community',
        sidebarPath: './sidebarsCommunity.js',
        // ... other options
      },
    ],
  ],
};

プラグインインスタンスには一意の id 属性を割り当てることを忘れないでください。

注意

product インスタンスが最も重要であると考え、ID を割り当てないことで「デフォルト」インスタンスにしています。

バージョン付きパス

各プラグインインスタンスは、バージョン付きドキュメントを別のフォルダーに保存します。

デフォルトのプラグインインスタンスは、以下のパスを使用します。

website/versions.json
website/versioned_docs
website/versioned_sidebars

他のプラグインインスタンス (id 属性を持つ) は、以下のパスを使用します。

website/[pluginId]_versions.json
website/[pluginId]_versioned_docs
website/[pluginId]_versioned_sidebars

ヒント

docs プラグインインスタンスの 1 つの id 属性 (デフォルトは default) は省略できます。

インスタンスパスがよりシンプルになり、単一インスタンス設定との下位互換性があります。

新しいバージョンのタグ付け

各プラグインインスタンスには、新しいバージョンにタグ付けするための独自の CLI コマンドがあります。これらは、以下を実行すると表示されます。

npm
Yarn
pnpm

npm run docusaurus -- --help

yarn docusaurus --help

pnpm run docusaurus --help

製品/デフォルトの docs プラグインインスタンスをバージョン管理するには

npm
Yarn
pnpm

npm run docusaurus docs:version 1.0.0

yarn docusaurus docs:version 1.0.0

pnpm run docusaurus docs:version 1.0.0

デフォルト以外の/コミュニティ docs プラグインインスタンスをバージョン管理するには

npm
Yarn
pnpm

npm run docusaurus docs:version:community 1.0.0

yarn docusaurus docs:version:community 1.0.0

pnpm run docusaurus docs:version:community 1.0.0

ドキュメント関連のテーマのナビゲーションバー項目には、オプションの docsPluginId 属性が指定できます。

たとえば、モバイル SDK (iOS および Android) ごとに 1 つのバージョンドロップダウンを表示する場合は、次のように記述できます。

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'docsVersionDropdown',
          docsPluginId: 'ios',
        },
        {
          type: 'docsVersionDropdown',
          docsPluginId: 'android',
        },
      ],
    },
  },
};

ユースケース​

モバイル SDK ドキュメント​

バージョン付きドキュメントとバージョンなしドキュメント​

セットアップ​

バージョン付きパス​

新しいバージョンのタグ付け​

ドキュメントのナビゲーションバー項目​