Docusaurus多实例文档管理指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00248/article/details/148324167

Docusaurus多实例文档管理指南

docusaurus Easy to maintain open source documentation websites. 项目地址: https://gitcode.com/gh_mirrors/do/docusaurus

前言

在现代技术文档管理中，我们经常需要处理多种不同类型的文档集合。Docusaurus作为一款优秀的静态网站生成器，提供了强大的多实例文档管理功能，能够帮助开发者高效组织复杂的文档结构。

什么是多实例文档管理

多实例文档管理是指在一个Docusaurus项目中同时维护多个独立的文档集合，每个集合可以有自己的版本控制、侧边栏配置和发布周期。这种架构特别适合以下场景：

跨平台SDK文档（如iOS和Android）
产品文档与社区文档分离
不同团队维护的独立文档集合

核心概念解析

插件实例ID

每个文档插件实例都需要一个唯一标识符（ID）。默认实例可以省略ID配置，系统会自动分配"default"作为其ID。

版本控制隔离

每个文档实例的版本信息会存储在独立文件中：

默认实例：versions.json
其他实例：[pluginId]_versions.json

典型应用场景

移动SDK文档管理

假设我们开发一个跨平台移动SDK，需要同时维护iOS和Android两套文档：

module.exports = {
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'ios',
        path: 'ios-docs',
        routeBasePath: 'ios',
        sidebarPath: './sidebarsIos.js'
      }
    ],
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'android',
        path: 'android-docs',
        routeBasePath: 'android',
        sidebarPath: './sidebarsAndroid.js'
      }
    ]
  ]
}

版本化与非版本化文档共存

某些文档需要版本控制，而有些则不需要。例如：

产品文档：需要版本控制
社区文档：不需要版本控制

module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          path: 'product',
          routeBasePath: 'product',
          sidebarPath: './sidebarsProduct.js'
        }
      }
    ]
  ],
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'community',
        path: 'community',
        routeBasePath: 'community',
        sidebarPath: './sidebarsCommunity.js'
      }
    ]
  ]
}

配置详解

基础配置要点

路径配置：每个实例应有独立的path和routeBasePath
侧边栏配置：为每个实例指定不同的sidebarPath
ID分配：非默认实例必须提供唯一ID

预设配置注意事项

当使用@docusaurus/preset-classic时，它已经包含了一个默认的docs插件实例。此时：

默认实例配置通过preset的docs选项进行
其他实例通过plugins数组添加

版本管理操作

创建新版本

每个文档实例都有独立的版本创建命令：

# 默认实例
npm run docusaurus docs:version 2.0.0

# 自定义ID实例
npm run docusaurus docs:version:community 1.0.0

版本文件结构

版本化文档会生成在特定目录：

默认实例：versioned_docs/和versioned_sidebars/
自定义实例：[pluginId]_versioned_docs/和[pluginId]_versioned_sidebars/

导航栏配置技巧

可以为每个文档实例配置独立的导航项：

module.exports = {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'docsVersionDropdown',
          docsPluginId: 'product'
        },
        {
          type: 'docsVersionDropdown',
          docsPluginId: 'community'
        }
      ]
    }
  }
}