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@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
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@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
52
53      - name: Configure Pages
54        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.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@fc324d3547104276b827a68afc52ff2a11cc49c9 # 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@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0