多實例文件

@docusaurus/plugin-content-docs 外掛可以支援 多實例。

備註

此功能僅適用於 版本化文件。建議您在閱讀此頁面之前先熟悉文件版本控制。如果您只需要 多個側邊欄，您可以在一個外掛中完成。

使用案例

有時您希望一個 Docusaurus 網站託管 2 個（或更多）不同的文件集。

這些文件甚至可能有不同的版本控制/發布生命週期。

行動 SDK 文件

如果您構建跨平台行動 SDK，您可能有 2 個文件

• Android SDK 文件（v1.0、v1.1）
• iOS SDK 文件（v1.0、v2.0）

在這種情況下，您可以為每個行動 SDK 文件使用不同的文件外掛實例。

警告

如果每個文件實例都非常大，您應該建立 2 個不同的 Docusaurus 網站。

如果有人編輯 iOS 文件，重新構建所有內容（包括未更改的整個 Android 文件）真的有用嗎？

版本化和非版本化文件

有時，您希望某些文件進行版本控制，而其他文件更「全局」，對它們進行版本控制感覺毫無用處。

我們在 Docusaurus 網站本身上使用這種模式

• /docs/* 部分是版本化的
• /community/* 部分是非版本化的

設定

假設您有 2 個文件

• 產品：一些關於您產品的版本化文件
• 社群：一些關於您產品周圍社群的非版本化文件

在這種情況下，您應該在網站設定中兩次使用相同的外掛。

警告

@docusaurus/preset-classic 已經為您包含了一個文件外掛實例！

使用預設集時

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

提示

您可以為其中一個文件外掛實例省略 id 屬性（預設為 default）。

實例路徑會更簡單，並且與單實例設定回溯相容。

標記新版本

每個外掛實例都有自己的 CLI 命令來標記新版本。如果您執行以下命令，它們將會顯示

npm

npm run docusaurus -- --help

Yarn

yarn docusaurus --help

pnpm

pnpm run docusaurus --help

要為 product/default 文件外掛實例進行版本控制

npm

npm run docusaurus docs:version 1.0.0

Yarn

yarn docusaurus docs:version 1.0.0

pnpm

pnpm run docusaurus docs:version 1.0.0

要為 non-default/community 文件外掛實例進行版本控制

npm

npm run docusaurus docs:version:community 1.0.0

Yarn

yarn docusaurus docs:version:community 1.0.0

pnpm

pnpm run docusaurus docs:version:community 1.0.0

文件導覽列項目

每個與文件相關的 主題導覽列項目 都採用一個可選的 docsPluginId 屬性。

例如，如果您希望每個行動 SDK（iOS 和 Android）都有一個版本下拉選單，您可以這樣做

docusaurus.config.js

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