如何用Git Submodule分离文档与代码？

在开源项目的维护过程中，你是否遇到过这样的困扰：文档geng新频繁触发主项目的 CI/CD 流程？文档部署配置与代码构建配置相互干扰？文档版本与代码版本难以同步？

本文将分享一个优雅的解决方案：使用 Git Submodule 将文档独立为单独仓库，实现文档的独立部署和版本管理，同时保持与主项目的关联。

在 AutoScan 项目的早期，文档直接放在主项目仓库中：

autoscan-spring-boot-starter/
├── docs/
│   └── zh/
├── src/
└── pom.xml

这种架构带来了一系列问题：

文档geng新会触发主项目的 CI/CD 流程，浪费资源

文档部署配置与代码构建配置相互干扰

文档版本与代码版本难以同步

通过 Git Submodule，我们Ke以将文档分离到独立的仓库，同时保持与主项目的关联。

┌─────────────────────────────────────────┐
│     autoscan-spring-boot-starter        │
│                               │
│                                         │
│  ┌─────────────────────────────────┐   │
│  │  docs/               │   │
│  │  └─> 指向 autoscan-docs 仓库     │   │
│  └─────────────────────────────────┘   │
│                                         │
│  src/                                   │
│  pom.xml                                │
│  README.md                              │
└─────────────────────────────────────────┘
                    │
                    │ submodule 引用
                    ▼
┌─────────────────────────────────────────┐
│          autoscan-docs                  │
│                                │
│                                         │
│  zh/                                    │
│  ├── index.html                         │
│  ├── version.js                         │
│  └── *.md                               │
│                                         │
│  .github/workflows/                     │
│  ├── update-doc-version.yml             │
│  └── deploy.yml                         │
└─────────────────────────────────────────┘

# 创建新的文档仓库
mkdir autoscan-docs
cd autoscan-docs
git init
# 创建目录结构
mkdir -p zh/js
# 创建文件
touch zh/index.html
touch zh/version.js
touch zh/_sidebar.md
touch zh/_coverpage.md
# 提交
git add .
git commit -m "init: 初始化文档仓库"
# 推送到远程
git remote add origin https://github.com/itrys/autoscan-docs.git
git push -u origin main

# 从主项目复制文档文件
cp -r ../autoscan-spring-boot-starter/docs/zh/* zh/
# 提交
git add .
git commit -m "docs: 迁移文档内容"
git push

# 进入主项目目录
cd ../autoscan-spring-boot-starter
# 删除原来的 docs 目录
rm -rf docs
# 添加 submodule
git submodule add https://github.com/itrys/autoscan-docs.git docs
# 提交
git add .
git commit -m "chore: 使用 submodule 引用文档仓库"
git push

创建 .github/workflows/deploy.yml

name: Deploy to GitHub Pages
on:
  push:
    branches:
      - main
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./

# geng新主项目代码并提交...
# geng新 submodule 并提交：
cd docs 
git pull origin main 
cd ..
git add docs 
git commit -m "docs: geng新 v1.1 文档"
git push origin main 
然后打 tag：
 git tag v1.1.0 
 git push --tags 
 

为每个大版本的分支,建立对应的 doc 分支。

例如 v1.x 对应 docs/v1.x。

这样在开发新特性时,docs/main 跟随开发分支,而稳定版本的doc则在对应的维护分支。

yml name : Update Docs Version on : push : tags : - 'v*'

jobs : update-docs : runs-on : ubuntu-latest steps :

# 根据 tag 版本geng新对应 docs 分支的引用

这个方案完美解决了我们的痛点:

独立部署各自用Zui合适的工具。

精确追踪每个代码版本的对应doc。

开发体验好该干嘛就干嘛,互不干扰。

省心省力自动化同步版本。

Ru果这篇文章对你有帮助，欢迎点赞、收藏、关注！ 🎉