如何在Docusaurus中整合多文件夹文档构建用户手册？

为什么你之前的方法无效 #

• @docusaurus/plugin-content-docs的path参数仅支持单个目录路径，不支持通配符或多路径配置，所以第一种用**通配符的方式根本不生效。
• 第二种把path设为根目录的方式，Docusaurus默认会启用文档版本化，它会去寻找current这类版本子目录，而你的根目录没有符合版本化结构的目录，所以抛出了文档不存在的错误，哪怕根目录有Intro.md也没用。

可行的解决方案 #

方案1：用软链接集中文档目录

在你的Docusaurus项目目录下，新建一个统一的文档目录（比如docusaurus/docs/user-manual），然后给每个Feature下的docs/user-manual里的文件创建软链接到这个统一目录：

• Linux/macOS：在终端执行

  # 先创建目标目录
  mkdir -p docusaurus/docs/user-manual
  # 遍历所有Feature下的user-manual文件，创建软链接
  for dir in src/Features/*/docs/user-manual/; do
    ln -s "$(realpath "$dir")"/* docusaurus/docs/user-manual/
  done
  

• Windows：用管理员权限打开命令提示符，执行

  # 创建目标目录
  mkdir docusaurus\docs\user-manual
  # 逐个创建软链接（以Feature1为例，其他Feature同理）
  mklink /D docusaurus\docs\user-manual\Feature1 src\Features\Feature1\docs\user-manual
  

之后修改Docusaurus的插件配置：

plugins: [
  [
    "@docusaurus/plugin-content-docs",
    {
      id: "user-manual",
      path: "./docs/user-manual", // 指向这个统一的软链接目录
      routeBasePath: "user-manual",
      sidebarPath: require.resolve("./sidebars.js"),
      versioning: false, // 不需要版本化可以关闭
    },
  ],
],

方案2：构建前用脚本同步文档

如果不想用软链接（比如跨平台兼容性问题），可以写一个脚本在Docusaurus构建前自动把所有Feature下的用户手册文件复制到统一目录：

1. 在Docusaurus目录下新建scripts/sync-docs.js脚本：

const fs = require('fs-extra');
const path = require('path');
const glob = require('glob');

// 目标目录
const targetDir = path.join(__dirname, '../docs/user-manual');
// 清空目标目录
fs.emptyDirSync(targetDir);

// 遍历所有源目录，复制文件
glob.sync('../../src/Features/*/docs/user-manual', { cwd: __dirname }).forEach(srcDir => {
  fs.copySync(srcDir, targetDir, {
    overwrite: true,
    recursive: true,
  });
});

2. 安装依赖fs-extra和glob：

npm install fs-extra glob --save-dev

3. 在package.json里修改构建脚本，加入同步步骤：

{
  "scripts": {
    "prebuild": "node scripts/sync-docs.js",
    "build": "docusaurus build",
    "prestart": "node scripts/sync-docs.js",
    "start": "docusaurus start"
  }
}

4. 最后同样修改插件配置指向./docs/user-manual即可，和方案1的配置一致。

方案3：调整include配置（仅适用于Docusaurus 2.4+）

如果不想用同步或软链接，可以尝试关闭版本化，正确配置include参数：

plugins: [
  [
    "@docusaurus/plugin-content-docs",
    {
      id: "user-manual",
      path: ".", // 根目录
      routeBasePath: "user-manual",
      sidebarPath: require.resolve("./sidebars.js"),
      versioning: false, // 必须关闭版本化，否则还是会找版本目录
      include: ["src/Features/**/docs/user-manual/*.md"], // 只包含指定路径的md文件
      exclude: ["**/node_modules/**", "**/.git/**"], // 排除不需要的文件
    },
  ],
],

注意：这种方式可能会让Docusaurus扫描大量文件，影响构建速度，而且如果你的文档有相对链接，可能会出现路径问题，所以优先推荐前两种方案。

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