文档多实例

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

• The /docs/* 部分是版本化的
• The /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

要对产品/默认文档插件实例进行版本控制

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

要对非默认/社区文档插件实例进行版本控制

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