docs.yml

name: Deploy Documentation

on:
  push:
    branches: [main]
  # Run the strict build on PRs too, so broken links / nav are caught
  # before merge instead of failing silently in the post-merge deploy.
  pull_request:
    branches: [main, 'release/**']
  workflow_dispatch:

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

# Cancel in-progress doc builds on the same ref when a newer commit arrives.
# Keyed by ref (NOT a global 'pages' group): a global group serialised every
# build/deploy across all refs behind one queue, so a stalled run wedged the
# whole pipeline for hours. Per-ref keying lets a PR build and the main-branch
# deploy proceed independently; the `github-pages` environment still serialises
# the actual deployment.
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

env:
  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true

jobs:
  build:
    # Build runs for push to main, dispatch, AND fork PRs (link/nav check).
    # Same-repo PRs and push run on aur0; fork PRs fall back to
    # ubuntu-latest so untrusted PR code never executes on aur0.
    runs-on: ${{ github.event.pull_request.head.repo.fork && 'ubuntu-latest' || fromJSON('["self-hosted", "aur0"]') }}
    steps:
      - uses: actions/checkout@v7

      - uses: actions/setup-python@v7
        with:
          python-version: '3.12'

      - name: Install docs dependencies
        run: pip install mkdocs-material mkdocs-minify-plugin

      - name: Build documentation
        run: mkdocs build --strict

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

  deploy:
    # Deploy only on push to main / manual dispatch — never for PR builds.
    if: github.event_name != 'pull_request'
    runs-on: [self-hosted, aur0]
    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