跳到主要内容

4、文档多实例

该文档创建于2024-09-04，最后更新于2024-09-03。

文档多实例​

@docusaurus/plugin-content-docs 插件可以支持 multi-instance。

信息

该功能仅对 版本化文档 有用。建议在阅读本页之前熟悉文档版本控制。如果你只想要 多个侧边栏，你可以在一个插件中完成此操作。

用例​

有时你希望 Docusaurus 站点托管 2 组不同的文档（或更多）。

这些文档甚至可能具有不同的版本控制/发布生命周期。

移动 SDK 文档​

如果你构建一个跨平台的移动 SDK，你可能有 2 个文档：

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

在这种情况下，你可以为每个移动 SDK 文档使用不同的文档插件实例。

警告

如果每个文档实例都非常大，你应该创建 2 个不同的 Docusaurus 站点。

如果有人编辑了 iOS 文档，那么重建所有内容（包括整个未更改的 Android 文档）真的有用吗？

版本化和非版本化文档​

有时候，你希望对某些文档进行版本控制，而其他文档则比较 "global"，感觉对它们进行版本控制没什么用。

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

设置​

假设你有 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 将其设为 "default" 实例。

版本化路径​

每个插件实例都会将版本化文档存储在不同的文件夹中。

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

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

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

  • npm
  • Yarn
  • pnpm
pnpm run docusaurus docs:version 1.0.0

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

  • npm
  • Yarn
  • 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',
        },
      ],
    },
  },
};
最后由 One 于 更新
0%