如何为GitHub Pages实现多部署：主站点与docs子路径分别部署

当然可以实现！我来一步步告诉你怎么把主站点和docs子路径分别部署到GitHub Pages上，完美适配你现在用的mystmd、sphinx构建工具，还有你的目录结构。

核心思路 #

GitHub Pages本质上是从指定分支（通常是gh-pages）的根目录读取静态文件来展示站点。所以我们只需要把主站点的构建产物放到gh-pages的根目录，把docs的构建产物放到gh-pages的docs子目录，就能实现你要的效果——主站点在https://myorg.github.io/my_repo_name，文档在https://myorg.github.io/my_repo_name/docs。

下面分两种方式来实现，推荐用GitHub Actions自动部署，省心又不容易出错。

方式一：用GitHub Actions自动部署（推荐） #

这种方式能让你每次提交代码后，自动完成构建和部署，不用手动操作。

1. 创建GitHub工作流文件
   在你的仓库根目录下新建.github/workflows/deploy-pages.yml文件，内容如下：

name: Deploy to GitHub Pages

on:
  push:
    branches: [ main ]  # 替换成你仓库的主分支名，比如master
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.10'  # 换成你项目用的Python版本

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install sphinx  # 安装sphinx依赖
          npm install -g mystmd  # 安装mystmd（如果用npm安装，或者换成你习惯的安装方式）

      - name: Build main site (mystmd)
        run: myst build  # 运行mystmd的构建命令，生成主站点到_build/html

      - name: Build docs (sphinx)
        working-directory: ./docs
        run: sphinx-build -b html . _build/html  # 生成docs到docs/_build/html

      - name: Prepare deployment files
        run: |
          mkdir -p deploy_dir
          # 把主站点内容复制到部署目录根目录
          cp -r _build/html/* deploy_dir/
          # 创建docs子目录，复制文档内容进去
          mkdir -p deploy_dir/docs
          cp -r docs/_build/html/* deploy_dir/docs/

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./deploy_dir

2. 配置GitHub Pages设置
   进入你的GitHub仓库，点击「Settings」→「Pages」，在「Build and deployment」部分，把「Source」设置为「Deploy from a branch」，然后选择「gh-pages」分支和「/(root)」目录，保存设置。

3. 测试部署
   提交并推送上面的工作流文件到主分支，GitHub会自动触发工作流，完成构建和部署。等几分钟后，你就能访问主站点和docs子路径了。

方式二：手动部署（适合临时测试） #

如果你不想用Actions，也可以手动把构建产物推到gh-pages分支：

1. 先构建好两个产物

   • 运行mystmd构建主站点：myst build，生成的文件在_build/html
   • 进入docs目录运行sphinx构建：cd docs && sphinx-build -b html . _build/html，生成的文件在docs/_build/html

2. 处理gh-pages分支

   # 切换到gh-pages分支，如果没有就创建
   git checkout -b gh-pages
   # 清空分支上的所有文件（注意：如果之前有内容，先备份需要保留的）
   git rm -rf .
   # 复制主站点内容到当前目录（gh-pages根目录）
   cp -r ../_build/html/* .
   # 创建docs目录并复制文档内容
   mkdir docs
   cp -r ../docs/_build/html/* docs/
   # 提交并推送
   git add .
   git commit -m "Deploy main site and docs"
   git push origin gh-pages
   

3. 同样需要在仓库设置里指定gh-pages分支作为部署来源

关键注意事项 #

• 路径配置：确保你的构建工具生成的静态文件内部链接正确。比如在sphinx的docs/conf.py里设置html_baseurl = "/my_repo_name/docs/"，mystmd的配置文件里设置site_url = "https://myorg.github.io/my_repo_name/"，这样页面跳转、资源引用才不会出问题。
• 权限问题：如果用GitHub Actions，确保仓库给了Actions足够的权限（默认的GITHUB_TOKEN一般就够用）。

备注：内容来源于stack exchange，提问作者brook