docs.yml

# ─────────────────────────────────────────────────────────────
# VextJS 文档站 — GitHub Pages 自动部署
#
# 触发条件：
#   - main 的 push-triggered CI 成功后，部署该次 CI 的精确 SHA
#   - 手动触发（workflow_dispatch）
#
# 流水线结构：
#   1. build  — 在 website/ 目录安装依赖并执行 rspress build
#   2. deploy — 部署到当前仓库 GitHub Pages: /vextjs/
#
# @see website/package.json §scripts
# @see https://rspress.dev/guide/start/deploy
# ─────────────────────────────────────────────────────────────

name: Deploy Docs

on:
  workflow_run:
    workflows: [CI]
    types: [completed]
    branches:
      - main
  workflow_dispatch:

# 同一分支同时只允许一个部署运行，新运行会取消旧运行
concurrency:
  group: pages-${{ github.event.workflow_run.head_branch || github.ref_name || github.run_id }}
  cancel-in-progress: true

# GitHub Pages 部署所需权限
permissions:
  contents: read
  pages: write
  id-token: write

# ── Jobs ─────────────────────────────────────────────────────

jobs:
  # ────────────────────────────────────────────────────────────
  # 1. 构建文档站
  # ────────────────────────────────────────────────────────────
  build:
    name: Build Docs
    runs-on: ubuntu-latest
    if: >-
      ${{
        github.event_name == 'workflow_dispatch' ||
        (
          github.event.workflow_run.conclusion == 'success' &&
          github.event.workflow_run.event == 'push' &&
          github.event.workflow_run.head_branch == 'main'
        )
      }}
    env:
      DEPLOY_SHA: ${{ github.event.workflow_run.head_sha || github.sha }}
    steps:
      - name: Checkout
        uses: actions/checkout@v7
        with:
          fetch-depth: 0 # 获取完整提交历史，rspress lastUpdated 功能需要
          ref: ${{ env.DEPLOY_SHA }}

      - name: Verify deployment commit
        if: github.event_name == 'workflow_run'
        shell: bash
        run: |
          ACTUAL_SHA=$(git rev-parse HEAD)
          if [[ "$ACTUAL_SHA" != "$DEPLOY_SHA" ]]; then
            echo "Expected CI SHA: $DEPLOY_SHA"
            echo "Checked out SHA: $ACTUAL_SHA"
            exit 1
          fi
          echo "Deploying successful CI SHA: $ACTUAL_SHA"

      - name: Resolve deployment target
        id: target
        shell: bash
        run: |
          echo "docs_base=/vextjs/" >> "$GITHUB_OUTPUT"
          echo "site_url=https://devcodex-labs.github.io/vextjs" >> "$GITHUB_OUTPUT"

      - name: Setup Node.js
        uses: actions/setup-node@v7
        with:
          node-version: 22
          cache: "npm"
          cache-dependency-path: website/package-lock.json

      - name: Setup GitHub Pages
        uses: actions/configure-pages@v6

      - name: Install dependencies
        working-directory: website
        run: npm ci

      - name: Install package dependencies and build CLI for docs verification
        run: npm ci && npm run build

      - name: Audit website production dependencies
        working-directory: website
        run: npm audit --omit=dev --audit-level=high

      - name: Build
        working-directory: website
        run: npm run build:publish -- --rollout=final
        env:
          NODE_ENV: production
          VEXT_DOCS_BASE: ${{ steps.target.outputs.docs_base }}
          VEXT_DOCS_SITE_URL: ${{ steps.target.outputs.site_url }}

      - name: Rewrite robots sitemap URL
        shell: bash
        run: |
          cat > website/dist/robots.txt <<EOF
          User-agent: *
          Allow: /

          Sitemap: ${{ steps.target.outputs.site_url }}/sitemap.xml
          EOF

      - name: Upload docs artifact
        uses: actions/upload-artifact@v7
        with:
          name: docs-dist
          path: website/dist

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v5
        with:
          path: website/dist

  # ────────────────────────────────────────────────────────────
  # 2a. 部署到当前仓库 GitHub Pages
  # ────────────────────────────────────────────────────────────
  deploy-pages:
    name: Deploy to GitHub Pages
    runs-on: ubuntu-latest
    needs: build

    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v5

      - name: Print deployment URL
        run: |
          echo "✅ 文档站已部署至: ${{ steps.deployment.outputs.page_url }}"