如何为带版本/非版本文件夹的多实例Docusaurus站点实现统一侧边栏

1. 统一定义侧边栏核心配置 #

在项目根目录的sidebars.js中，直接构建包含Android、iOS、Common三大分类的完整侧边栏结构，同时兼容版本化文档和全局文档：

module.exports = {
  unifiedSidebar: [
    {
      type: 'category',
      label: 'Android',
      items: [
        // 自动生成对应版本的Android文档列表
        {type: 'autogenerated', dirName: 'android'},
        // 可选：Android专属全局文档（如通用FAQ）
        'android/global/android-general-faq'
      ]
    },
    {
      type: 'category',
      label: 'iOS',
      items: [
        {type: 'autogenerated', dirName: 'ios'},
        'ios/global/ios-general-troubleshooting'
      ]
    },
    {
      type: 'category',
      label: 'Common',
      items: [
        // 全局通用文档直接指定路径
        'common/changelog',
        'common/license',
        'common/quick-start-guide'
      ]
    }
  ]
};

2. 多实例共享侧边栏配置 #

修改docusaurus.config.js，让所有文档实例（全局Common、版本化Android/iOS）都引用同一个sidebars.js：

module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          // 全局Common文档实例
          path: 'common',
          routeBasePath: 'common',
          sidebarPath: require.resolve('./sidebars.js'),
          sidebarCollapsible: false
        }
      }
    ]
  ],
  plugins: [
    // Android版本化文档实例
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'android',
        path: 'android',
        routeBasePath: 'android',
        sidebarPath: require.resolve('./sidebars.js'),
        versions: {
          current: {label: 'Android v1.0'},
          '0.9': {label: 'Android v0.9'}
        },
        sidebarCollapsible: false
      }
    ],
    // iOS版本化文档实例
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'ios',
        path: 'ios',
        routeBasePath: 'ios',
        sidebarPath: require.resolve('./sidebars.js'),
        versions: {
          current: {label: 'iOS v1.0'},
          '0.9': {label: 'iOS v0.9'}
        },
        sidebarCollapsible: false
      }
    ]
  ]
};

3. 对齐文档目录结构 #

• 版本化文档：确保android/versioned_docs/version-xxx、ios/versioned_docs/version-xxx下的文件结构和sidebars.js中dirName指定的android/ios路径匹配，自动生成逻辑会拉取对应版本的文档。
• 全局文档：将更新日志、许可证等放在common目录下，直接在侧边栏配置中指定文件名，确保所有实例都能访问。

4. 修复侧边栏高亮与版本兼容 #

• 保持各版本文档的sidebar_position一致，避免切换版本时高亮错位。
• 如果部分版本缺少特定文档，可通过条件判断控制侧边栏条目显示：

// 示例：仅在Android v1.0及以上显示新功能文档
items: [
  process.env.DOCUSAURUS_CURRENT_VERSION >= '1.0' ? 'android/new-feature' : null
].filter(Boolean)

内容的提问来源于stack exchange，提问作者m2u-84