docs.yml

name: Docs

on:
  pull_request:
  push:
    branches:
      - main

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

jobs:
  build:
    name: Build (strict)
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
      - name: Set up uv
        uses: astral-sh/setup-uv@v7
        with:
          python-version: "3.13"
      - name: Install extras + docs
        run: uv sync --frozen --all-extras --group docs
      # Cairo + imaging libs for the Material `social` plugin (og:/twitter cards).
      # The plugin is gated to CI (CI=true) in mkdocs.yml; these are its system deps.
      - name: Install Cairo (social cards)
        run: sudo apt-get update && sudo apt-get install -y libcairo2-dev libfreetype6-dev libffi-dev libjpeg-dev libpng-dev libz-dev pngquant
      - name: Validate mermaid diagrams
        run: uv run python scripts/validate_mermaid.py
      - name: Build docs (strict)
        run: uv run mkdocs build --strict
      - name: Configure Pages
        if: github.ref == 'refs/heads/main'
        uses: actions/configure-pages@v6
        with:
          enablement: true
      - name: Upload Pages artifact
        if: github.ref == 'refs/heads/main'
        uses: actions/upload-pages-artifact@v5
        with:
          path: site

  deploy:
    name: Deploy GitHub Pages
    if: github.ref == 'refs/heads/main'
    needs: build
    runs-on: ubuntu-latest
    # Scope concurrency to deploy job only; PR builds never wait
    # behind deploy. Never cancel deploy mid-publish.
    concurrency:
      group: pages
      cancel-in-progress: false
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy
        id: deployment
        uses: actions/deploy-pages@v5
      - name: Verify Pages live (HTTP 200)
        run: |
          url="${{ steps.deployment.outputs.page_url }}"
          status=$(curl -o /dev/null -s -w "%{http_code}" "$url")
          echo "HTTP status: $status"
          [ "$status" = "200" ]