文档站与静态站点发布流水线

源码（Markdown / MDX / 组件）
        │  build（Hugo / Docusaurus / MkDocs）
        ▼
   静态产物目录（public/ dist/ site/）
        │  artifact 上传
        ▼
   部署目标（Pages / CDN / 对象存储）

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

name: Docs

on:
  push:
    branches: [main]
    paths:
      - "docs/**"
      - "content/**"
      - "package.json"
  pull_request:
    paths:
      - "docs/**"
      - "content/**"

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0   # Hugo 需要完整历史计算 .Lastmod

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - run: npm ci
      - run: npm run docs:build

      - uses: actions/upload-artifact@v4
        with:
          name: site
          path: dist/

- name: Setup Hugo
  uses: peaceiris/actions-hugo@v3
  with:
    hugo-version: "0.128.0"
    extended: true

- name: Build
  run: hugo --minify --gc
  env:
    HUGO_ENVIRONMENT: production
    HUGO_ENV: production

- run: npm ci
- run: npm run build
  env:
    NEXT_TELEMETRY_DISABLED: "1"

- uses: actions/cache@v4
  with:
    path: .next/cache
    key: next-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
    restore-keys: next-${{ runner.os }}-

- uses: actions/setup-python@v5
  with:
    python-version: "3.12"
    cache: pip

- run: pip install -r requirements.txt
- run: mkdocs build --strict

jobs:
  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    permissions:
      pages: write
      id-token: write
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: site
          path: dist

      - uses: actions/configure-pages@v5

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

      - id: deployment
        uses: actions/deploy-pages@v4

concurrency:
  group: pages-deploy
  cancel-in-progress: false   # 让进行中的部署跑完，避免半成品

- name: Publish to Cloudflare Pages
  uses: cloudflare/wrangler-action@v3
  with:
    apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
    accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
    command: pages deploy dist --project-name=my-docs --branch=${{ github.head_ref || github.ref_name }}

- run: npm i -g vercel@latest
- run: vercel pull --yes --environment=preview --token=${{ secrets.VERCEL_TOKEN }}
- run: vercel build --token=${{ secrets.VERCEL_TOKEN }}
- run: vercel deploy --prebuilt --token=${{ secrets.VERCEL_TOKEN }}

- name: Sync to S3
  run: |
    aws s3 sync dist/ s3://my-docs-bucket/ \
      --delete \
      --cache-control "public, max-age=31536000, immutable" \
      --exclude "*.html" \
      --exclude "*.xml"
    aws s3 sync dist/ s3://my-docs-bucket/ \
      --cache-control "public, max-age=0, must-revalidate" \
      --exclude "*" --include "*.html" --include "*.xml"

- name: Comment preview URL
  uses: actions/github-script@v7
  with:
    script: |
      const url = "${{ steps.deploy.outputs.url }}";
      const marker = "<!-- docs-preview -->";
      const body = `${marker}\n📄 文档预览：${url}`;
      const { data: comments } = await github.rest.issues.listComments({
        ...context.repo, issue_number: context.issue.number,
      });
      const prev = comments.find(c => c.body.includes(marker));
      if (prev) {
        await github.rest.issues.updateComment({ ...context.repo, comment_id: prev.id, body });
      } else {
        await github.rest.issues.createComment({ ...context.repo, issue_number: context.issue.number, body });
      }

- name: Check links
  uses: lycheeverse/lychee-action@v2
  with:
    args: --no-progress --max-retries 2 --accept 200,206 "dist/**/*.html"
    fail: true

- run: hugo --minify --gc --panicOnWarning

- name: Lighthouse CI
  run: |
    npm i -g @lhci/cli
    lhci autorun
  env:
    LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_GITHUB_APP_TOKEN }}

// lighthouserc.json
{
  "ci": {
    "assert": {
      "assertions": {
        "categories:performance": ["error", { "minScore": 0.9 }],
        "categories:accessibility": ["error", { "minScore": 0.95 }]
      }
    }
  }
}

aws cloudfront create-invalidation \
  --distribution-id ABCDEF123456 \
  --paths "/logo.png" "/favicon.ico"

- uses: actions/upload-artifact@v4
  with:
    name: site-${{ github.sha }}
    path: dist/
    retention-days: 90