build-docs.yml

name: Build docs

# Builds the GitHub Pages site with `mkdocs build --strict` on every pull
# request, so a change that would break the site is caught before it merges
# rather than by deploy-docs.yml after it, and again after each push to `main`.
# It only builds; it deploys nothing and doesn't change the site.
#
# mkdocs-material is pinned to the same version deploy-docs.yml installs. Its
# own dependencies aren't pinned, here or in the deploy, so a new release of
# one of them can still change a build.
#
# NOTE: advisory until an admin adds "build-docs" to the required status checks
# for `main`. Use "Require branches to be up to date before merging" with it
# rather than a merge queue: the workflow doesn't run on merge_group events.

on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]
    # Deliberately NOT filtered with `paths:`: a required check that never runs
    # stays pending forever.
  push:
    branches: [main]

permissions:
  contents: read

# A new push to a pull request cancels its older build. Builds of `main` are
# never cancelled, so every push to it is built.
concurrency:
  group: build-docs-${{ github.event.pull_request.number || github.sha }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

jobs:
  build-docs:
    name: build-docs
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
        with:
          persist-credentials: false

      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
        with:
          python-version: "3.12"

      - name: Install mkdocs
        run: python3 -I -m pip install mkdocs-material==9.6.14

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