deploy-docs-pages.yml

name: Deploy Docs To GitHub Pages

on:
  push:
    branches:
      - main
    paths:
      - docs/**
      - scripts/build-docs-pages.js
      - .github/workflows/deploy-docs-pages.yml
  workflow_dispatch:

permissions:
  contents: write

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

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

      - name: Setup Node
        uses: actions/setup-node@v5
        with:
          node-version: 22
          cache: npm

      - name: Install Dependencies
        run: npm ci

      - name: Build Docs Site
        run: node scripts/build-docs-pages.js

      - name: Publish To gh-pages Branch
        shell: bash
        run: |
          set -euo pipefail

          PUBLISH_DIR="${RUNNER_TEMP}/gh-pages"

          # Clean up stale worktree path from prior attempts.
          git worktree remove --force "$PUBLISH_DIR" 2>/dev/null || true
          rm -rf "$PUBLISH_DIR"

          git fetch origin gh-pages || true

          if git show-ref --verify --quiet refs/remotes/origin/gh-pages; then
            git worktree add "$PUBLISH_DIR" refs/remotes/origin/gh-pages
          else
            git worktree add -B gh-pages "$PUBLISH_DIR"
          fi

          # Keep worktree git metadata intact.
          rsync -av --delete --exclude='.git' .site/ "$PUBLISH_DIR"/
          touch "$PUBLISH_DIR/.nojekyll"

          cd "$PUBLISH_DIR"
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"

          git add --all
          if git diff --cached --quiet; then
            echo "No docs changes to publish"
            exit 0
          fi

          git commit -m "Deploy docs for ${GITHUB_SHA}"
          git push origin HEAD:gh-pages