Skip to main content

複数のインスタンス

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

メモ

この機能は、バージョン管理されたドキュメントにのみ有効です。 このページを読む前に、docsのバージョン管理について熟知しておくことをお勧めします。 もし、複数のサイドバーが欲しいだけなら、1つのプラグイン内で可能です。

利用例​

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

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

モバイル SDK​

クロスプラットフォームのモバイル SDK を構築する場合、2つのドキュメントを用意することがあります:

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

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

警告

それぞれのドキュメントのインスタンスが非常に大きい場合は、2つの異なる Docusarus サイトを作成してください。

誰かが iOS のドキュメントを編集した場合、変更しなかった Android のドキュメントも含めて、すべてを再構築することは本当に便利ですか?

バージョン管理されたドキュメントとバージョン管理されていないドキュメント​

あるドキュメントをバージョン管理したい一方で、他のドキュメントはもっと「グローバル」であり、バージョン管理するのは無駄だと感じることがあります。

Docusaurus のウェブサイト自体でも、このパターンを利用しています:

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

セットアップ​

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

  • Product: 製品に関するバージョン管理されたドキュメント
  • Community: 製品関連のバージョン管理されていないドキュメント

この場合、サイト構成で同じプラグインを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 を割り当てないで「デフォルト」インスタンスにしています。

バージョン管理されたパス​

それぞれのプラグインインスタンスは、バージョン管理された docs を個別のフォルダーに保存します。

デフォルトのプラグインインスタンスはこれらのパスを利用します:

  • 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 run docusaurus -- --help

Product / デフォルトの docs プラグインインスタンスをバージョンアップする:

npm run docusaurus docs:version 1.0.0

デフォルトでない / Communityの docs プラグインインスタンスをバージョンアップする:

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