跳转至主内容
Version: 2.0.0-beta.3

多实例文档

@docusaurus/plugin-content-docs 插件支持多个实例。

note

此功能仅适合分版文档。 我们推荐您先了解分版文档，再阅读此页面。

使用场景#

有时候，您想要 Docusaurus 提供两种（或更多）完全不同的文档。

这些文档甚至可能有着不同的版本/发行周期。

移动设备 SDK 文档#

若您正为移动设备 SDK 撰写文档，您可能会有以下两种版本：

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

这种情况下，您应在不同版本的 SDK 文档中使用不同的文档插件实例。

caution

若文档较多，您应创建两个 Docusaurus 站点。

假设有人编辑了 iOS 的文档，此时真的有必要同时重新构建未修改的 Android 文档吗？

分版及未分版文档#

有时候，您需要提供不同版本的文档，而其他文档则更为“全局”，没有必要去为它们创建多个版本。

我们在 Docusaurus 网站上就使用了这种模式：

设置#

假设您有两种文档：

  • 产品：多个版本的产品文档
  • 社区：单一版本的社区文档

这种情况下，您应在站点配置中复用相同的插件。

caution

@docusaurus/preset-classic 已经自带了文档插件实例！

若使用此预设：

docusaurus.config.js
module.exports = {  presets: [    [      '@docusaurus/preset-classic',      {        docs: {          // id: 'product', // 忽略 => 默认实例          path: 'product',          routeBasePath: 'product',          sidebarPath: require.resolve('./sidebarsProduct.js'),          // ... 其他选项        },      },    ],  ],  plugins: [    [      '@docusaurus/plugin-content-docs',      {        id: 'community',        path: 'community',        routeBasePath: 'community',        sidebarPath: require.resolve('./sidebarsCommunity.js'),        // ... 其他设置      },    ],  ],};

不使用此预设时：

docusaurus.config.js
module.exports = {  plugins: [    [      '@docusaurus/plugin-content-docs',      {        // id: 'product', // 忽略 => 默认实例        path: 'product',        routeBasePath: 'product',        sidebarPath: require.resolve('./sidebarsProduct.js'),        // ... 其他设置      },    ],    [      '@docusaurus/plugin-content-docs',      {        id: 'community',        path: 'community',        routeBasePath: 'community',        sidebarPath: require.resolve('./sidebarsCommunity.js'),        // ... 其他设置      },    ],  ],};

请别忘记为每个插件实例添加唯一的 id 属性。

note

我们的重心放在 product 实例上，因此将其设置为“默认”实例，不分配 id。

分版路径#

每个插件实例都会把版本化文档存储在一个单独的文件夹中。

默认的插件实例会使用这些路径：

  • website/versions.json
  • website/versioned_docs
  • website/versioned_sidebars

其他插件实例（包含 id 属性）会使用这些路径：

  • website/<pluginId>_versions.json
  • website/<pluginId>_versioned_docs
  • website/<pluginId>_versioned_sidebars
tip

你可以省略其中一个文档插件实例的 id 属性（它会被默认置为 default）。

实例路径将更简单，并且与单实例配置兼容。

标记新版本#

每个插件实例都有自己的 cli 命令来标记一个新版本。 如果你运行下列指令，它们就会被显示：

npm run docusaurus -- --help

要为产品内提供的或默认文档插件实例添加版本：

npm run docusaurus docs:version 1.0.0

要为非默认或社区维护的文档插件实例添加版本：

npm run docusaurus docs:version:community 1.0.0

文档导航栏项目#

每个文档相关的主题导航栏项目都接受一个可选的 DocPluginId 属性。

比如，如果你想要为每个移动 SDK（iOS 和 Android）添加一个版本下拉框，你可以这么做：

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