GitBook多仓库文档合并及子模块同步问题咨询

一、GitBook 支持子模块文档合并吗？ #

可以实现，GitBook 本身不直接识别 Git 子模块，但通过两种方式能整合子模块内的文档：

1. 用符号链接映射 #

在主仓库的 docs/ 目录下创建软链接，指向子模块的文档目录。以 sub-module-1/docs 为例：

# 进入主仓库的 docs 目录执行
ln -s ../libs/sub-module-1/docs sub-module-1-docs

GitBook 构建时会自动识别软链接指向的 Markdown 文件，将其纳入整体文档体系。

2. 修改 book.json 配置 #

在主仓库根目录的 book.json 中，通过 structure 字段指定多路径文档源：

{
  "structure": {
    "docs": [
      "./docs",
      "./libs/sub-module-1/docs",
      "./libs/sub-module-2/docs"
    ]
  }
}

这种方式无需创建软链接，GitBook 会直接遍历指定目录收集所有文档。

二、子模块文档的同步机制 #

当主仓库关联子模块的特定提交哈希时，子模块文档的更新需遵循以下流程：

1. 修改子模块文档：直接在 sub-module-1 仓库中编辑 docs/install.md，完成后提交并推送到远程仓库。
2. 更新主仓库的子模块引用：切换到主仓库，进入子模块目录拉取最新提交：

cd libs/sub-module-1
git pull origin main # 假设子模块默认分支为 main
cd ../..

然后提交主仓库中子模块的哈希更新：

git add libs/sub-module-1
git commit -m "更新 sub-module-1 到最新提交"
git push origin main

3. 重新构建 GitBook：此时主仓库的 GitBook 会使用子模块的最新文档内容。

若想简化同步，可使用 git submodule update --remote 命令，它会自动拉取子模块的远程最新提交并更新主仓库引用，适合无需固定子模块版本的场景。

三、最优组织建议 #

• 保持子模块文档目录独立，每个子模块的文档都放在自身 docs/ 下，主仓库通过配置或软链接统一整合，避免结构冲突。
• 在主仓库的 SUMMARY.md 中明确子模块文档的入口，让读者清晰识别文档归属，示例：

# Summary
- 主仓库文档
  - 入门指南
- 子模块1文档
  - [安装说明](libs/sub-module-1/docs/install.md)
  - [使用教程](libs/sub-module-1/docs/blah.md)
- 子模块2文档
  - ...

• 若需频繁同步子模块，可编写简单 shell 脚本，批量更新所有子模块并提交主仓库的引用变更，减少手动操作。

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