跳到主要内容

文档多实例

@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 网站本身使用这种模式：

设置​

假设您有 2 个文档：

  • 产品：关于您的产品的一些版本化文档
  • 社区：关于您的产品周围社区的一些非版本化文档

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

注意

@docusaurus/preset-classic 已经为您包含了一个文档插件实例！

使用预设时：

docusaurus.config.js
export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          // id: 'product', // 省略 => 默认实例
          path: 'product',
          routeBasePath: 'product',
          sidebarPath: './sidebarsProduct.js',
          // ... 其他选项
        },
      },
    ],
  ],
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'community',
        path: 'community',
        routeBasePath: 'community',
        sidebarPath: './sidebarsCommunity.js',
        // ... 其他选项
      },
    ],
  ],
};

不使用预设时：

docusaurus.config.js
export default {
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        // id: 'product', // 省略 => 默认实例
        path: 'product',
        routeBasePath: 'product',
        sidebarPath: './sidebarsProduct.js',
        // ... 其他选项
      },
    ],
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'community',
        path: 'community',
        routeBasePath: 'community',
        sidebarPath: './sidebarsCommunity.js',
        // ... 其他选项
      },
    ],
  ],
};

不要忘记为插件实例分配唯一的 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 run docusaurus -- --help

标记产品/默认文档插件实例的版本：

npm run docusaurus docs:version 1.0.0

标记非默认/社区文档插件实例的版本：

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