krz/orgo

 1name: Docs
 2
 3# Publish the documentation site to GitHub Pages.
 4#
 5# The site is fifteen org files under docs/, built by the tool they document — so this
 6# job is also the most honest smoke test in the repository: if orgo cannot build its own
 7# documentation, the deploy fails and says so.
 8#
 9# `--strict` makes a broken internal link a build failure. Docs rot by having their links
10# quietly stop resolving, and that is exactly the failure a static site generator is
11# supposed to be able to catch.
12
13on:
14  push:
15    branches: [main]
16    # Templates and the config shape the pages as much as the prose does, and a change to
17    # the renderer changes every page. Anything else — a test, a fixture — cannot.
18    paths:
19      - "docs/**"
20      - "src/**"
21      - "Cargo.toml"
22      - "Cargo.lock"
23      - ".github/workflows/docs.yml"
24  workflow_dispatch:
25
26# Read the repository, write a Pages deployment. Nothing else.
27permissions:
28  contents: read
29  pages: write
30  id-token: write
31
32# One deployment at a time, and let a newer commit win: a queue of doc builds racing each
33# other to publish is worse than the last one arriving late.
34concurrency:
35  group: pages
36  cancel-in-progress: true
37
38jobs:
39  build:
40    runs-on: ubuntu-latest
41    steps:
42      - name: Checkout
43        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
44
45      - name: Install Rust
46        uses: dtolnay/rust-toolchain@1ff72ee08e3cb84d84adba594e0a297990fc1ed3 # stable
47        with:
48          toolchain: stable
49
50      - name: Cache cargo
51        uses: Swatinem/rust-cache@98c8021b550208e191a6a3145459bfc9fb29c4c0 # v2.8.0
52
53      - name: Configure Pages
54        uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5.0.0
55
56      # Built with the release profile: the docs deploy is also the only place a release
57      # build runs outside a tag, so a break in it surfaces here rather than at release.
58      - name: Build the site
59        run: cargo run --release --locked -- build docs -o docs/_site --strict
60
61      - name: Upload the artifact
62        uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v3.0.1
63        with:
64          path: docs/_site
65
66  deploy:
67    needs: build
68    runs-on: ubuntu-latest
69    environment:
70      name: github-pages
71      url: ${{ steps.deployment.outputs.page_url }}
72    steps:
73      - name: Deploy
74        id: deployment
75        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5