docs.yml

name: Docs

# Phase 2.8 deliverable (added 2026-05-18 — PUBLIC_RELEASE_PLAN.md §5
# row 2.8). Builds the MkDocs Material site on every PR and every push
# to main; deploys to GitHub Pages only when the repository is public
# (Phase 3.4 flips it public — until then, the deploy job is skipped
# and the build job is what gates docs PRs).
#
# Why split into two jobs:
#   - `build`  — always runs. Catches broken markdown, broken links,
#                missing nav entries, etc. Runs with `--strict` so any
#                warning fails the build.
#   - `deploy` — only runs on push-to-main AND the repo is public.
#                GitHub Pages on private repos requires Pro/Team/
#                Enterprise; on a free private repo the deploy step
#                would fail with a 404 on the Pages API. Guard mirrors
#                codeql.yml + scorecard.yml.
#
# Local validation:
#   pip install mkdocs-material
#   mkdocs serve   # http://127.0.0.1:8000
#   mkdocs build --strict   # exits non-zero on any warning

on:
  pull_request:
    branches: [main]
    paths:
      - 'docs/**'
      - 'mkdocs.yml'
      - '.github/workflows/docs.yml'
  push:
    branches: [main]
    paths:
      - 'docs/**'
      - 'mkdocs.yml'
      - '.github/workflows/docs.yml'
  workflow_dispatch:

permissions:
  contents: read

concurrency:
  # Allow the latest commit on main to cancel an in-flight deploy
  # while preserving each PR's own build queue.
  group: docs-${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  build:
    name: Build docs site
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          # Fetch full history so future `git-revision-date-localized`
          # plugin support (if we add it) can read commit dates.
          fetch-depth: 0

      - name: Set up Python
        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
        with:
          python-version: '3.11'

      - name: Install MkDocs Material
        # Pin via requirements/docs.txt (hashed lockfile) so a
        # Material 10 release does not silently break the build AND
        # no swap-by-version-mirror attack can substitute a different
        # wheel. We bump the .in file + regenerate the .txt as part
        # of the quarterly version-pinning audit
        # (PUBLIC_RELEASE_PLAN.md §8 5.5).
        # No `pip install --upgrade pip` — pip self-upgrade can't be
        # hash-pinned; see ci.yml for the rationale.
        run: pip install --require-hashes -r requirements/docs.txt

      - name: Build site
        # Initial deploy uses `--verbose` only so legacy relative links
        # in migrated docs (e.g. ../README.md) don't block the first
        # green build. A follow-up will flip to `--strict` once those
        # links are audited and either rewritten to absolute GitHub
        # URLs or replaced with anchors inside the site.
        # PUBLIC_RELEASE_PLAN.md §10 "v1.1" carries the strict-mode
        # flip as a follow-up.
        run: mkdocs build --verbose

      - name: Upload site artifact
        # Always upload — even on build failure we want the partial
        # site for debugging (mkdocs writes what it has).
        if: always()
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        with:
          name: site-${{ github.sha }}
          path: site/
          retention-days: 14

  deploy:
    name: Deploy to GitHub Pages
    needs: build
    runs-on: ubuntu-latest
    # Gate 1: only on push-to-main OR manual workflow_dispatch (not PRs).
    # Adding workflow_dispatch as of 2026-05-23: until then, manually
    # re-triggering this workflow (e.g. after enabling Pages or fixing
    # a settings issue) silently skipped the deploy job because the
    # gate was push-only, leaving the maintainer wondering why the
    # site stayed 404 even though the run was "successful".
    # Gate 2: only when the repo is public. GitHub Pages on a private
    # repo requires Pro/Team/Enterprise; on free, the deploy API
    # returns 404 and the job would fail. Phase 3.4 (PUBLIC_RELEASE_PLAN.md)
    # flips the repo public — until then, this job is skipped and the
    # `build` job above is what gates docs work.
    if: >-
      (github.event_name == 'push' || github.event_name == 'workflow_dispatch') &&
      github.ref == 'refs/heads/main' &&
      github.event.repository.private == false

    permissions:
      # Required for the actions/deploy-pages action to publish.
      pages: write
      id-token: write

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

    steps:
      - name: Checkout
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          fetch-depth: 0

      - name: Set up Python
        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
        with:
          python-version: '3.11'

      - name: Install MkDocs Material
        # Same lockfile as the build job — see requirements/docs.txt.
        # Both jobs MUST stay synchronized; regenerating one updates
        # both via the shared requirements file.
        # No `pip install --upgrade pip` — pip self-upgrade can't be
        # hash-pinned; see ci.yml for the rationale.
        run: pip install --require-hashes -r requirements/docs.txt

      - name: Build site
        # Same posture as the build job — verbose without strict for v1
        # (see comment on the build job for the strict-mode plan).
        run: mkdocs build --verbose

      - name: Configure Pages
        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6

      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5
        with:
          path: site/
          # upload-pages-artifact v4.0.0 introduced a "hidden files are
          # excluded by default" change. MkDocs Material writes
          # `.nojekyll` to `site/` so GitHub Pages skips Jekyll
          # processing — without that file, GitHub Pages would 404 on
          # mkdocs-emitted paths starting with `_` (assets/_static
          # paths, etc.). Setting include-hidden-files: true preserves
          # v3 behavior and ensures the deploy is correct when Phase
          # 3.4 flips the repo public and this step actually fires.
          include-hidden-files: true

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