mkdocs GitHub Pages 自动部署¶

目的：用 GitHub Actions 自动部署 docs 到 GitHub Pages 关联：[B1-10]

1. 完整 GitHub Actions 配置¶

# .github/workflows/docs.yml
name: Deploy Docs
on:
  push:
    branches: [main]
    paths:
      - 'learn_doc/**'
      - 'docs/**'
      - 'mkdocs.yml'
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - run: pip install -r requirements-docs.txt

      - run: mkdocs build --strict

      - uses: actions/configure-pages@v5

      - uses: actions/upload-pages-artifact@v3
        with:
          path: site

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4

~50 行。

2. 5 步集成¶

2.1 Step 1: 创建 workflow¶

mkdir -p .github/workflows
# 写 docs.yml

1 文件。

2.2 Step 2: 配 GitHub Pages¶

Settings → Pages → Source: GitHub Actions

1 设置。

2.3 Step 3: 配 permissions¶

permissions:
  pages: write
  id-token: write

2 行。

2.4 Step 4: trigger¶

on:
  push:
    paths: ['learn_doc/**', 'docs/**', 'mkdocs.yml']

3 path。

2.5 Step 5: 部署¶

# 推 main → 自动部署
git push

1 推。

3. 5 个 deploy 选项¶

选项	优点	缺点
GitHub Pages + Actions	免费 / 自动	公开
Netlify	快	配置多
Vercel	快速	商业
Cloudflare Pages	CDN	复杂
自建	完全控制	维护

5 选项。

4. 5 个最佳实践¶

strict mode —— build fail = 有错
concurrency group —— 避免 race
环境保护 —— main 分支
不动 gh-pages 分支 —— 用 Actions
PR 预览 —— pull_request 触发

5. PR 预览¶

on:
  pull_request:
    paths: ['learn_doc/**']
jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install -r requirements-docs.txt
      - run: mkdocs build
      - uses: actions/upload-artifact@v4
        with:
          name: docs-preview
          path: site

PR 时 build + artifact 下载。

6. 5 个反模式¶

❌ 用 gh-pages 分支
❌ 不用 strict
❌ 不用 permissions
❌ 不写环境
❌ 在 main 直接 build

7. 完整 .github/workflows¶

.github/
├── workflows/
│   ├── docs.yml         # 部署
│   ├── test.yml         # 测试（推测）
│   └── lint.yml         # lint

3 workflow。

8. 总结¶

GitHub Pages 部署 = 50 行 Actions + 5 步。

下一步： - 看 B2 GitHub 配置