如何在Docusaurus的docs目录中管理多课程的不同版本？

针对你的需求，最清晰且可维护的实现方式是为每门课程配置独立的文档插件实例，让每个课程拥有专属的版本管理体系，互不干扰。以下是具体实现步骤：

1. 调整目录结构 #

按课程划分文档根目录，每个课程下再按版本存放文档：

docs/
├── course-a/
│   ├── current/          # Course A 当前版本（比如v2.0）的所有文档
│   └── v1.0/             # Course A 旧版本文档
├── course-b/
│   └── current/          # Course B 当前版本（比如v1.5）的所有文档
└── course-c/
    ├── current/          # Course C 当前版本（比如v3.0）的所有文档
    └── v2.1/             # Course C 旧版本文档

2. 修改docusaurus.config.js配置 #

移除原presets中的docs配置，改用多插件实例的方式，每门课程对应一个@docusaurus/plugin-content-docs插件：

module.exports = {
  presets: ['@docusaurus/preset-classic'],
  plugins: [
    // 课程A的文档插件
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'course-a',
        docsPath: 'docs/course-a',
        routeBasePath: 'course-a',
        lastVersion: 'current',
        versions: {
          current: {
            label: 'Course A v2.0',
            path: 'v2.0',
          },
          'v1.0': {
            label: 'Course A v1.0',
            path: 'v1.0',
          },
        },
      },
    ],
    // 课程B的文档插件
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'course-b',
        docsPath: 'docs/course-b',
        routeBasePath: 'course-b',
        lastVersion: 'current',
        versions: {
          current: {
            label: 'Course B v1.5',
            path: 'v1.5',
          },
        },
      },
    ],
    // 课程C的文档插件
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'course-c',
        docsPath: 'docs/course-c',
        routeBasePath: 'course-c',
        lastVersion: 'current',
        versions: {
          current: {
            label: 'Course C v3.0',
            path: 'v3.0',
          },
          'v2.1': {
            label: 'Course C v2.1',
            path: 'v2.1',
          },
        },
      },
    ],
  ],
  // 配置导航栏入口，关联各课程文档
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'docSidebar',
          sidebarId: 'course-aSidebar',
          position: 'left',
          label: 'Course A',
          docsPluginId: 'course-a',
        },
        {
          type: 'docSidebar',
          sidebarId: 'course-bSidebar',
          position: 'left',
          label: 'Course B',
          docsPluginId: 'course-b',
        },
        {
          type: 'docSidebar',
          sidebarId: 'course-cSidebar',
          position: 'left',
          label: 'Course C',
          docsPluginId: 'course-c',
        },
      ],
    },
  },
};

3. 配置各课程的侧边栏 #

在sidebars.js中为每门课程创建独立的侧边栏配置：

module.exports = {
  course-aSidebar: [
    {
      type: 'category',
      label: 'Course A 核心内容',
      items: [/* 填入Course A的文档路径 */],
    },
  ],
  course-bSidebar: [
    {
      type: 'category',
      label: 'Course B 核心内容',
      items: [/* 填入Course B的文档路径 */],
    },
  ],
  course-cSidebar: [
    {
      type: 'category',
      label: 'Course C 核心内容',
      items: [/* 填入Course C的文档路径 */],
    },
  ],
};

方案优势 #

• 每个课程的版本管理完全独立，新增/删除版本不会影响其他课程
• 路由结构清晰，用户可通过/course-a/v2.0、/course-c/v2.1等路径直接访问对应版本的课程文档
• 维护成本低，各课程文档物理隔离，避免版本混淆

内容的提问来源于stack exchange，提问作者Patrick Collins