docs.yml

# Builds the MkDocs Material docs site with `--strict` and publishes it to GitHub
# Pages. The strict build runs on every PR as a check so a broken nav entry or
# internal link fails before merge; on push to the stable branch (main) the built
# site is pushed directly to the gh-pages branch, which GitHub Pages serves as a
# classic branch-served site (no GitHub Pages deploy-API / Actions source needed).
name: docs

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

# Allow only one concurrent deployment; do not cancel an in-progress run so a
# deploy completes before the next starts.
concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  # Strict build. Runs on PRs and pushes alike, so the same gate that protects
  # merges also produces the site pushed to gh-pages on main.
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: Checkout
        uses: actions/checkout@v5

      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: "3.12"

      - name: Install docs dependencies
        run: pip install -r docs/requirements.txt

      - name: Build the site (strict)
        run: mkdocs build --strict

      # Publish only on push to the stable branch. PRs run the build gate above
      # but never publish.
      - name: Publish to gh-pages
        if: github.ref == 'refs/heads/main'
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./site
          publish_branch: gh-pages