name: 发布官网与文档站

# 把一个 GitHub Pages 站点发出去：
#
#   /                产品官网（website/，纯静态、无构建步骤）
#   /docs/           文档站（docfx 构建 docs/ 得到）
#
# 为什么要拼成一个站点：**一个仓库在 GitHub Pages 上只有一个站点**。两者发布节奏也不一样
# （改个错别字就该上线，不该为此打个安装包），所以走 workflow 而不是塞进发布流程。
#
# 站点地址：https://lovechengke.github.io/ClassHelper/
# 需要在仓库 Settings → Pages 里把 Source 选成「GitHub Actions」（只需做一次）。
#
# 本地预览：pnpm dev:site（官网在 :5180，文档站挂在同一个端口的 /docs/ 下）

on:
  push:
    branches: [master]
    paths:
      - 'website/**'
      - 'docs/**'
      - 'scripts/build-pages.mjs'
      - '.github/workflows/pages.yml'
      # 两个页面上的版本号都取自根 package.json
      # （官网是手写的徽章，文档站由 docs/build.mjs 用 --metadata 注入），
      # 所以版本号变了也要重新发一次
      - 'package.json'
  workflow_dispatch:

# Pages 部署需要的三件套：读代码、写 Pages、用 OIDC 拿部署令牌
permissions:
  contents: read
  pages: write
  id-token: write

# 同一时间只跑一个部署；已经在跑的那次不取消（半途取消会留下一个坏掉的站点）
concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    steps:
      - name: 检出代码
        uses: actions/checkout@v4

      - name: 安装 .NET SDK 8
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '8.0.x'

      - name: 安装 docfx
        # docfx 是 .NET 全局工具，装完在 ~/.dotnet/tools 下；setup-dotnet 会把它加进 PATH，
        # 这里再显式补一次，免得换 runner 镜像后找不到命令。
        run: |
          dotnet tool install --global docfx
          echo "$HOME/.dotnet/tools" >> "$GITHUB_PATH"

      - name: 构建文档站
        # --check 把 docfx 的警告当错误：最常见的警告是"某个 .md 没被任何 toc.yml 引用"，
        # 那种页面会被构建出来但没有侧边栏 —— 属于必须修掉的疏漏，不该悄悄上线。
        #
        # DOCS_BASE 是给文档站那份 404 用的：项目页挂在 /<仓库名>/ 子路径下，而浏览器按
        # **被请求的路径**解析 404 页里的相对链接，所以要把站点根钉成 <base>。
        env:
          DOCS_BASE: /${{ github.event.repository.name }}/docs/
        run: node docs/build.mjs --check

      - name: 组装站点（官网在根，文档站在 /docs/）
        env:
          SITE_BASE: /${{ github.event.repository.name }}/
        run: node scripts/build-pages.mjs

      - name: 配置 Pages
        uses: actions/configure-pages@v5

      - name: 上传构建产物
        uses: actions/upload-pages-artifact@v3
        with:
          path: .cache/pages

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