name: Docs

# Publish the documentation site to GitHub Pages.
#
# The site is fifteen org files under docs/, built by the tool they document — so this
# job is also the most honest smoke test in the repository: if orgo cannot build its own
# documentation, the deploy fails and says so.
#
# `--strict` makes a broken internal link a build failure. Docs rot by having their links
# quietly stop resolving, and that is exactly the failure a static site generator is
# supposed to be able to catch.

on:
  push:
    branches: [main]
    # Templates and the config shape the pages as much as the prose does, and a change to
    # the renderer changes every page. Anything else — a test, a fixture — cannot.
    paths:
      - "docs/**"
      - "src/**"
      - "Cargo.toml"
      - "Cargo.lock"
      - ".github/workflows/docs.yml"
  workflow_dispatch:

# Read the repository, write a Pages deployment. Nothing else.
permissions:
  contents: read
  pages: write
  id-token: write

# One deployment at a time, and let a newer commit win: a queue of doc builds racing each
# other to publish is worse than the last one arriving late.
concurrency:
  group: pages
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - name: Install Rust
        uses: dtolnay/rust-toolchain@1ff72ee08e3cb84d84adba594e0a297990fc1ed3 # stable
        with:
          toolchain: stable

      - name: Cache cargo
        uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2

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

      # Built with the release profile: the docs deploy is also the only place a release
      # build runs outside a tag, so a break in it surfaces here rather than at release.
      - name: Build the site
        run: cargo run --release --locked -- build docs -o docs/_site --strict

      - name: Upload the artifact
        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v3.0.1
        with:
          path: docs/_site

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy
        id: deployment
        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0