fix: doc pages (take 2!) (#1327)

.github/docs-0.1.0.patch

@@ -53,3 +53,33 @@ index 0000000..9eb0697
 +
 +common --noenable_bzlmod
 +build --workspace_status_command=tools/workspace_status.sh
+diff --git a/docs/stardoc_repository.bzl b/docs/stardoc_repository.bzl
+index 2153aa8..7c63be7 100644
+--- a/docs/stardoc_repository.bzl
++++ b/docs/stardoc_repository.bzl
+@@ -7,9 +7,9 @@ def stardoc_repository():
+     maybe(
+         http_archive,
+         name = "io_bazel_stardoc",
++        sha256 = "3fd8fec4ddec3c670bd810904e2e33170bedfe12f90adf943508184be458c8bb",
+         urls = [
+-            "https://github.com/bazelbuild/stardoc/archive/a0f330bcbae44ffc59d50a86a830a661b8d18acc.zip",
++            "https://mirror.bazel.build/github.com/bazelbuild/stardoc/releases/download/0.5.3/stardoc-0.5.3.tar.gz",
++            "https://github.com/bazelbuild/stardoc/releases/download/0.5.3/stardoc-0.5.3.tar.gz",
+         ],
+-        sha256 = "e12831c6c414325c99325726dd26dabd8ed4c9efa7b4f27b4d1d9594ec7dfc40",
+-        strip_prefix = "stardoc-a0f330bcbae44ffc59d50a86a830a661b8d18acc",
+     )
+diff --git a/docs/tools/workspace_status.sh b/docs/tools/workspace_status.sh
+new file mode 100755
+index 0000000..5ceb3f7
+--- /dev/null
++++ b/docs/tools/workspace_status.sh
+@@ -0,0 +1,7 @@
++#!/usr/bin/env bash
++
++set -euo pipefail
++
++echo STABLE_SCM_SHORT_VERSION "$(git rev-parse --short HEAD)"
++echo STABLE_SCM_VERSION "$(git rev-parse HEAD)"
++echo STABLE_RELEASE "$(cat ../version.bzl | grep VERSION | sed 's/VERSION = "//' | sed 's/"//')"

.github/docs-0.2.0.patch

@@ -53,3 +53,33 @@ index 0000000..9eb0697
 +
 +common --noenable_bzlmod
 +build --workspace_status_command=tools/workspace_status.sh
+diff --git a/docs/stardoc_repository.bzl b/docs/stardoc_repository.bzl
+index 2153aa8..7c63be7 100644
+--- a/docs/stardoc_repository.bzl
++++ b/docs/stardoc_repository.bzl
+@@ -7,9 +7,9 @@ def stardoc_repository():
+     maybe(
+         http_archive,
+         name = "io_bazel_stardoc",
++        sha256 = "3fd8fec4ddec3c670bd810904e2e33170bedfe12f90adf943508184be458c8bb",
+         urls = [
+-            "https://github.com/bazelbuild/stardoc/archive/a0f330bcbae44ffc59d50a86a830a661b8d18acc.zip",
++            "https://mirror.bazel.build/github.com/bazelbuild/stardoc/releases/download/0.5.3/stardoc-0.5.3.tar.gz",
++            "https://github.com/bazelbuild/stardoc/releases/download/0.5.3/stardoc-0.5.3.tar.gz",
+         ],
+-        sha256 = "e12831c6c414325c99325726dd26dabd8ed4c9efa7b4f27b4d1d9594ec7dfc40",
+-        strip_prefix = "stardoc-a0f330bcbae44ffc59d50a86a830a661b8d18acc",
+     )
+diff --git a/docs/tools/workspace_status.sh b/docs/tools/workspace_status.sh
+new file mode 100755
+index 0000000..5ceb3f7
+--- /dev/null
++++ b/docs/tools/workspace_status.sh
+@@ -0,0 +1,7 @@
++#!/usr/bin/env bash
++
++set -euo pipefail
++
++echo STABLE_SCM_SHORT_VERSION "$(git rev-parse --short HEAD)"
++echo STABLE_SCM_VERSION "$(git rev-parse HEAD)"
++echo STABLE_RELEASE "$(cat ../version.bzl | grep VERSION | sed 's/VERSION = "//' | sed 's/"//')"

.github/docs-0.3.0.patch

@@ -47,7 +47,7 @@ index 3a91e41..14c8e3b 100644
      name = "rules_foreign_cc",
 -    sha256 = "d54742ffbdc6924f222d2179f0e10e911c5c659c4ae74158e9fe827aad862ac6",
 -    strip_prefix = "rules_foreign_cc-0.2.0",
--    url = "https://github.com/bazel-contrib/rules_foreign_cc/archive/0.2.0.tar.gz",
+-    url = "https://github.com/bazelbuild/rules_foreign_cc/archive/0.2.0.tar.gz",
 +    # TODO: Get the latest sha256 value from the latest release on the releases page
 +    #       https://github.com/bazel-contrib/rules_foreign_cc/releases
 +    #
@@ -93,3 +93,33 @@ index 0000000..9eb0697
 +
 +common --noenable_bzlmod
 +build --workspace_status_command=tools/workspace_status.sh
+diff --git a/docs/stardoc_repository.bzl b/docs/stardoc_repository.bzl
+index 2153aa8..7c63be7 100644
+--- a/docs/stardoc_repository.bzl
++++ b/docs/stardoc_repository.bzl
+@@ -7,9 +7,9 @@ def stardoc_repository():
+     maybe(
+         http_archive,
+         name = "io_bazel_stardoc",
++        sha256 = "3fd8fec4ddec3c670bd810904e2e33170bedfe12f90adf943508184be458c8bb",
+         urls = [
+-            "https://github.com/bazelbuild/stardoc/archive/a0f330bcbae44ffc59d50a86a830a661b8d18acc.zip",
++            "https://mirror.bazel.build/github.com/bazelbuild/stardoc/releases/download/0.5.3/stardoc-0.5.3.tar.gz",
++            "https://github.com/bazelbuild/stardoc/releases/download/0.5.3/stardoc-0.5.3.tar.gz",
+         ],
+-        sha256 = "e12831c6c414325c99325726dd26dabd8ed4c9efa7b4f27b4d1d9594ec7dfc40",
+-        strip_prefix = "stardoc-a0f330bcbae44ffc59d50a86a830a661b8d18acc",
+     )
+diff --git a/docs/tools/workspace_status.sh b/docs/tools/workspace_status.sh
+new file mode 100755
+index 0000000..5ceb3f7
+--- /dev/null
++++ b/docs/tools/workspace_status.sh
+@@ -0,0 +1,7 @@
++#!/usr/bin/env bash
++
++set -euo pipefail
++
++echo STABLE_SCM_SHORT_VERSION "$(git rev-parse --short HEAD)"
++echo STABLE_SCM_VERSION "$(git rev-parse HEAD)"
++echo STABLE_RELEASE "$(cat ../version.bzl | grep VERSION | sed 's/VERSION = "//' | sed 's/"//')"

.github/docs-0.4.0.patch

@@ -24,3 +24,30 @@ index dc6a3f7..9eb0697 100644
 +
 +common --noenable_bzlmod
  build --workspace_status_command=tools/workspace_status.sh
+diff --git a/docs/stardoc_repository.bzl b/docs/stardoc_repository.bzl
+index 2153aa8..7c63be7 100644
+--- a/docs/stardoc_repository.bzl
++++ b/docs/stardoc_repository.bzl
+@@ -7,9 +7,9 @@ def stardoc_repository():
+     maybe(
+         http_archive,
+         name = "io_bazel_stardoc",
++        sha256 = "3fd8fec4ddec3c670bd810904e2e33170bedfe12f90adf943508184be458c8bb",
+         urls = [
+-            "https://github.com/bazelbuild/stardoc/archive/a0f330bcbae44ffc59d50a86a830a661b8d18acc.zip",
++            "https://mirror.bazel.build/github.com/bazelbuild/stardoc/releases/download/0.5.3/stardoc-0.5.3.tar.gz",
++            "https://github.com/bazelbuild/stardoc/releases/download/0.5.3/stardoc-0.5.3.tar.gz",
+         ],
+-        sha256 = "e12831c6c414325c99325726dd26dabd8ed4c9efa7b4f27b4d1d9594ec7dfc40",
+-        strip_prefix = "stardoc-a0f330bcbae44ffc59d50a86a830a661b8d18acc",
+     )
+diff --git a/docs/tools/workspace_status.sh b/docs/tools/workspace_status.sh
+index eaec25a..5ceb3f7 100755
+--- a/docs/tools/workspace_status.sh
++++ b/docs/tools/workspace_status.sh
+@@ -1,4 +1,4 @@
+-#!/bin/bash
++#!/usr/bin/env bash
+ 
+ set -euo pipefail
+ 

.github/docs-0.5.0.patch

@@ -11,3 +11,30 @@ index dc6a3f7..9eb0697 100644
 +
 +common --noenable_bzlmod
  build --workspace_status_command=tools/workspace_status.sh
+diff --git a/docs/stardoc_repository.bzl b/docs/stardoc_repository.bzl
+index 2153aa8..7c63be7 100644
+--- a/docs/stardoc_repository.bzl
++++ b/docs/stardoc_repository.bzl
+@@ -7,9 +7,9 @@ def stardoc_repository():
+     maybe(
+         http_archive,
+         name = "io_bazel_stardoc",
++        sha256 = "3fd8fec4ddec3c670bd810904e2e33170bedfe12f90adf943508184be458c8bb",
+         urls = [
+-            "https://github.com/bazelbuild/stardoc/archive/a0f330bcbae44ffc59d50a86a830a661b8d18acc.zip",
++            "https://mirror.bazel.build/github.com/bazelbuild/stardoc/releases/download/0.5.3/stardoc-0.5.3.tar.gz",
++            "https://github.com/bazelbuild/stardoc/releases/download/0.5.3/stardoc-0.5.3.tar.gz",
+         ],
+-        sha256 = "e12831c6c414325c99325726dd26dabd8ed4c9efa7b4f27b4d1d9594ec7dfc40",
+-        strip_prefix = "stardoc-a0f330bcbae44ffc59d50a86a830a661b8d18acc",
+     )
+diff --git a/docs/tools/workspace_status.sh b/docs/tools/workspace_status.sh
+index eaec25a..5ceb3f7 100755
+--- a/docs/tools/workspace_status.sh
++++ b/docs/tools/workspace_status.sh
+@@ -1,4 +1,4 @@
+-#!/bin/bash
++#!/usr/bin/env bash
+ 
+ set -euo pipefail
+ 

.github/docs-0.5.1.patch

@@ -11,3 +11,30 @@ index dc6a3f7..9eb0697 100644
 +
 +common --noenable_bzlmod
  build --workspace_status_command=tools/workspace_status.sh
+diff --git a/docs/stardoc_repository.bzl b/docs/stardoc_repository.bzl
+index 2153aa8..7c63be7 100644
+--- a/docs/stardoc_repository.bzl
++++ b/docs/stardoc_repository.bzl
+@@ -7,9 +7,9 @@ def stardoc_repository():
+     maybe(
+         http_archive,
+         name = "io_bazel_stardoc",
++        sha256 = "3fd8fec4ddec3c670bd810904e2e33170bedfe12f90adf943508184be458c8bb",
+         urls = [
+-            "https://github.com/bazelbuild/stardoc/archive/a0f330bcbae44ffc59d50a86a830a661b8d18acc.zip",
++            "https://mirror.bazel.build/github.com/bazelbuild/stardoc/releases/download/0.5.3/stardoc-0.5.3.tar.gz",
++            "https://github.com/bazelbuild/stardoc/releases/download/0.5.3/stardoc-0.5.3.tar.gz",
+         ],
+-        sha256 = "e12831c6c414325c99325726dd26dabd8ed4c9efa7b4f27b4d1d9594ec7dfc40",
+-        strip_prefix = "stardoc-a0f330bcbae44ffc59d50a86a830a661b8d18acc",
+     )
+diff --git a/docs/tools/workspace_status.sh b/docs/tools/workspace_status.sh
+index eaec25a..5ceb3f7 100755
+--- a/docs/tools/workspace_status.sh
++++ b/docs/tools/workspace_status.sh
+@@ -1,4 +1,4 @@
+-#!/bin/bash
++#!/usr/bin/env bash
+ 
+ set -euo pipefail
+ 

.github/docs-0.6.0.patch

@@ -11,3 +11,30 @@ index dc6a3f7..9eb0697 100644
 +
 +common --noenable_bzlmod
  build --workspace_status_command=tools/workspace_status.sh
+diff --git a/docs/stardoc_repository.bzl b/docs/stardoc_repository.bzl
+index 2153aa8..7c63be7 100644
+--- a/docs/stardoc_repository.bzl
++++ b/docs/stardoc_repository.bzl
+@@ -7,9 +7,9 @@ def stardoc_repository():
+     maybe(
+         http_archive,
+         name = "io_bazel_stardoc",
++        sha256 = "3fd8fec4ddec3c670bd810904e2e33170bedfe12f90adf943508184be458c8bb",
+         urls = [
+-            "https://github.com/bazelbuild/stardoc/archive/a0f330bcbae44ffc59d50a86a830a661b8d18acc.zip",
++            "https://mirror.bazel.build/github.com/bazelbuild/stardoc/releases/download/0.5.3/stardoc-0.5.3.tar.gz",
++            "https://github.com/bazelbuild/stardoc/releases/download/0.5.3/stardoc-0.5.3.tar.gz",
+         ],
+-        sha256 = "e12831c6c414325c99325726dd26dabd8ed4c9efa7b4f27b4d1d9594ec7dfc40",
+-        strip_prefix = "stardoc-a0f330bcbae44ffc59d50a86a830a661b8d18acc",
+     )
+diff --git a/docs/tools/workspace_status.sh b/docs/tools/workspace_status.sh
+index eaec25a..5ceb3f7 100755
+--- a/docs/tools/workspace_status.sh
++++ b/docs/tools/workspace_status.sh
+@@ -1,4 +1,4 @@
+-#!/bin/bash
++#!/usr/bin/env bash
+ 
+ set -euo pipefail
+ 

.github/docs-0.7.0.patch

@@ -11,3 +11,20 @@ index dc6a3f7..9eb0697 100644
 +
 +common --noenable_bzlmod
  build --workspace_status_command=tools/workspace_status.sh
+diff --git a/docs/stardoc_repository.bzl b/docs/stardoc_repository.bzl
+index 2153aa8..7c63be7 100644
+--- a/docs/stardoc_repository.bzl
++++ b/docs/stardoc_repository.bzl
+@@ -7,9 +7,9 @@ def stardoc_repository():
+     maybe(
+         http_archive,
+         name = "io_bazel_stardoc",
++        sha256 = "3fd8fec4ddec3c670bd810904e2e33170bedfe12f90adf943508184be458c8bb",
+         urls = [
+-            "https://github.com/bazelbuild/stardoc/archive/a0f330bcbae44ffc59d50a86a830a661b8d18acc.zip",
++            "https://mirror.bazel.build/github.com/bazelbuild/stardoc/releases/download/0.5.3/stardoc-0.5.3.tar.gz",
++            "https://github.com/bazelbuild/stardoc/releases/download/0.5.3/stardoc-0.5.3.tar.gz",
+         ],
+-        sha256 = "e12831c6c414325c99325726dd26dabd8ed4c9efa7b4f27b4d1d9594ec7dfc40",
+-        strip_prefix = "stardoc-a0f330bcbae44ffc59d50a86a830a661b8d18acc",
+     )

.github/docs-0.7.1.patch

@@ -11,3 +11,20 @@ index dc6a3f7..9eb0697 100644
 +
 +common --noenable_bzlmod
  build --workspace_status_command=tools/workspace_status.sh
+diff --git a/docs/stardoc_repository.bzl b/docs/stardoc_repository.bzl
+index 2153aa8..7c63be7 100644
+--- a/docs/stardoc_repository.bzl
++++ b/docs/stardoc_repository.bzl
+@@ -7,9 +7,9 @@ def stardoc_repository():
+     maybe(
+         http_archive,
+         name = "io_bazel_stardoc",
++        sha256 = "3fd8fec4ddec3c670bd810904e2e33170bedfe12f90adf943508184be458c8bb",
+         urls = [
+-            "https://github.com/bazelbuild/stardoc/archive/a0f330bcbae44ffc59d50a86a830a661b8d18acc.zip",
++            "https://mirror.bazel.build/github.com/bazelbuild/stardoc/releases/download/0.5.3/stardoc-0.5.3.tar.gz",
++            "https://github.com/bazelbuild/stardoc/releases/download/0.5.3/stardoc-0.5.3.tar.gz",
+         ],
+-        sha256 = "e12831c6c414325c99325726dd26dabd8ed4c9efa7b4f27b4d1d9594ec7dfc40",
+-        strip_prefix = "stardoc-a0f330bcbae44ffc59d50a86a830a661b8d18acc",
+     )

.github/docs-0.8.0.patch

@@ -11,3 +11,20 @@ index dc6a3f7..9eb0697 100644
 +
 +common --noenable_bzlmod
  build --workspace_status_command=tools/workspace_status.sh
+diff --git a/docs/stardoc_repository.bzl b/docs/stardoc_repository.bzl
+index 2153aa8..7c63be7 100644
+--- a/docs/stardoc_repository.bzl
++++ b/docs/stardoc_repository.bzl
+@@ -7,9 +7,9 @@ def stardoc_repository():
+     maybe(
+         http_archive,
+         name = "io_bazel_stardoc",
++        sha256 = "3fd8fec4ddec3c670bd810904e2e33170bedfe12f90adf943508184be458c8bb",
+         urls = [
+-            "https://github.com/bazelbuild/stardoc/archive/a0f330bcbae44ffc59d50a86a830a661b8d18acc.zip",
++            "https://mirror.bazel.build/github.com/bazelbuild/stardoc/releases/download/0.5.3/stardoc-0.5.3.tar.gz",
++            "https://github.com/bazelbuild/stardoc/releases/download/0.5.3/stardoc-0.5.3.tar.gz",
+         ],
+-        sha256 = "e12831c6c414325c99325726dd26dabd8ed4c9efa7b4f27b4d1d9594ec7dfc40",
+-        strip_prefix = "stardoc-a0f330bcbae44ffc59d50a86a830a661b8d18acc",
+     )

.github/docs-0.9.0.patch

@@ -11,3 +11,20 @@ index dc6a3f7..9eb0697 100644
 +
 +common --noenable_bzlmod
  build --workspace_status_command=tools/workspace_status.sh
+diff --git a/docs/stardoc_repository.bzl b/docs/stardoc_repository.bzl
+index 2153aa8..7c63be7 100644
+--- a/docs/stardoc_repository.bzl
++++ b/docs/stardoc_repository.bzl
+@@ -7,9 +7,9 @@ def stardoc_repository():
+     maybe(
+         http_archive,
+         name = "io_bazel_stardoc",
++        sha256 = "3fd8fec4ddec3c670bd810904e2e33170bedfe12f90adf943508184be458c8bb",
+         urls = [
+-            "https://github.com/bazelbuild/stardoc/archive/a0f330bcbae44ffc59d50a86a830a661b8d18acc.zip",
++            "https://mirror.bazel.build/github.com/bazelbuild/stardoc/releases/download/0.5.3/stardoc-0.5.3.tar.gz",
++            "https://github.com/bazelbuild/stardoc/releases/download/0.5.3/stardoc-0.5.3.tar.gz",
+         ],
+-        sha256 = "e12831c6c414325c99325726dd26dabd8ed4c9efa7b4f27b4d1d9594ec7dfc40",
+-        strip_prefix = "stardoc-a0f330bcbae44ffc59d50a86a830a661b8d18acc",
+     )

.github/workflows/pages.yaml

@@ -1,4 +1,5 @@
 name: Generate docs
+
 on:
   pull_request:
     branches:
@@ -9,111 +10,187 @@ on:
   push:
     branches:
       - main
+
+env:
+  BAZELISK_VERSION: 1.23.0
+  MDBOOK_VERSION: 0.4.42
+
+  GH_REPO: ${{ github.repository }}
+  MIN_VERSION: ${{ github.event.inputs.MIN_VERSION || '0.1.0' }}
+  FILTER_VERSION: ${{ github.event.inputs.FILTER_VERSION || '' }}
+  RELEASE_TAG_REGEX: ^\d+\.\d+\.\d+$
+
 jobs:
-  pages:
+  setup:
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        # Create a job for release
-        include:
-          - ref: main
-          - ref: "0.12.0"
-          - ref: "0.11.1"
-          - ref: "0.11.0"
-          - ref: "0.10.1"
-          - ref: "0.9.0"
-          - ref: "0.8.0"
-          - ref: "0.7.1"
-          - ref: "0.7.0"
-          - ref: "0.6.0"
-          - ref: "0.5.1"
-          - ref: "0.5.0"
-          - ref: "0.4.0"
-          - ref: "0.3.0"
-          - ref: "0.2.0"
-          - ref: "0.1.0"
+
+    defaults:
+      run:
+        shell: bash --noprofile --norc -euo pipefail {0}
+
     steps:
-      - uses: actions/checkout@v2
-        if: ${{ matrix.ref == 'main' }}
-      - uses: actions/checkout@v2
+      - name: get release tags that match $release_tag_regex
+        id: get_release_tags
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          RELEASES_JSON="$(
+            curl -s --fail-with-body \
+              -H "Authorization: token $GH_TOKEN" \
+              "https://api.github.com/repos/$GH_REPO/tags"
+          )"
+
+          RELEASES_JSON_FILTERED="$(echo "$RELEASES_JSON" |
+            jq -c \
+              --arg RELEASE_TAG_REGEX "$RELEASE_TAG_REGEX" \
+              --arg FILTER_VERSION "$FILTER_VERSION" \
+              --arg MIN_VERSION "$MIN_VERSION" '
+              [ "main" ] +
+              ([.[].name |
+                 select(
+                   (test($RELEASE_TAG_REGEX) and
+                    (. | split(".") | map(tonumber) >= ($MIN_VERSION | split(".") | map(tonumber)))
+                   ) and ($FILTER_VERSION == "" or . == $FILTER_VERSION)
+                 )
+              ])
+              '
+          )"
+          echo "releases=$RELEASES_JSON_FILTERED"
+          echo "releases=$RELEASES_JSON_FILTERED" >> "$GITHUB_OUTPUT"
+
+    outputs:
+      releases: ${{ steps.get_release_tags.outputs.releases || '[]' }}
+
+  build:
+    runs-on: ubuntu-latest
+    needs: setup
+
+    defaults:
+      run:
+        shell: bash --noprofile --norc -euo pipefail {0}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        ref: ${{ fromJson(needs.setup.outputs.releases) }}
+
+    env:
+      WORKSPACE: ${{ github.workspace }}
+      BIN: ${{ github.workspace }}/bin
+
+    steps:
+      - name: Checkout $REF
+        uses: actions/checkout@v4
         with:
           ref: ${{ matrix.ref }}
-        if: ${{ matrix.ref != 'main' }}
-      - name: Pin the release to main
-        run: echo "RELEASE=main" >> $GITHUB_ENV
-        if: ${{ matrix.ref == 'main' }}
-      - name: Patch older branches
+
+      - name: Patch $REF
+        env:
+          REF: ${{ matrix.ref }}
         run: |
-          ref="${{ matrix.ref }}"
+          [[ "$REF" == "main" ]] && exit
 
-          [[ "$ref" == "main" ]] && exit
+          PATCH=".github/docs-${REF}.patch"
 
-          v_major="$(echo "$ref" | cut -d. -f1)"
-          v_minor="$(echo "$ref" | cut -d. -f2)"
-          v_patch="$(echo "$ref" | cut -d. -f3)"
+          URL="https://raw.githubusercontent.com/$GH_REPO/main/$PATCH"
+          echo "$URL"
 
-          [[ $v_minor -gt 10 ]] && exit
+          curl -LO --fail-with-body "$URL" || {
+              echo "No patch found for $REF, exiting..."
+              exit 0
+          }
+
+          echo "Patching ref: $REF"
+          git apply "$(basename "$PATCH")"
 
-          mkdir -p ${{ github.workspace }}/.github
-          curl https://raw.githubusercontent.com/bazel-contrib/rules_foreign_cc/main/.github/docs-${{ matrix.ref }}.patch > ${{ github.workspace }}/.github/docs-${{ matrix.ref }}.patch
-          git apply ${{ github.workspace }}/.github/docs-${{ matrix.ref }}.patch
       - name: Install bazelisk
         run: |
-          curl -LO "https://github.com/bazelbuild/bazelisk/releases/download/v1.9.0/bazelisk-linux-amd64"
-          mkdir -p "${{ github.workspace }}/bin/"
-          mv bazelisk-linux-amd64 "${{ github.workspace }}/bin/bazel"
-          chmod +x "${{ github.workspace }}/bin/bazel"
-      - name: Generate docs
-        run: |
-          "${{ github.workspace }}/bin/bazel" run //:generate_docs
-          "${{ github.workspace }}/bin/bazel" clean
-        working-directory: ${{ github.workspace }}/docs
+          BAZELISK="bazelisk-linux-amd64"
+
+          URL="https://github.com/bazelbuild/bazelisk/releases/download/v$BAZELISK_VERSION/$BAZELISK"
+          echo "URL=$URL"
+          curl -LO --fail-with-body "$URL"
+
+          chmod +x "$BAZELISK"
+
+          mkdir -p "$BIN"
+          mv "$BAZELISK" "$BIN/bazel"
+
       - name: Install mdbook
         run: |
-          curl -LO "https://github.com/rust-lang/mdBook/releases/download/v0.4.10/mdbook-v0.4.10-x86_64-unknown-linux-gnu.tar.gz"
-          mkdir -p "${{ github.workspace }}/bin/"
-          tar -xvf mdbook-v0.4.10-x86_64-unknown-linux-gnu.tar.gz
-          mv mdbook "${{ github.workspace }}/bin/mdbook"
-          chmod +x "${{ github.workspace }}/bin/mdbook"
-      - name: mdbook build
-        run: ${{ github.workspace }}/bin/mdbook build
+          MDBOOK="mdbook-v$MDBOOK_VERSION-x86_64-unknown-linux-gnu.tar.gz"
+
+          URL="https://github.com/rust-lang/mdBook/releases/download/v$MDBOOK_VERSION/$MDBOOK"
+          echo "URL=$URL"
+          curl -LO --fail-with-body "$URL"
+
+          tar -xvf "$MDBOOK"
+          chmod +x mdbook
+
+          mkdir -p "$BIN"
+          mv mdbook "$BIN/mdbook"
+
+      - name: bazel run //:generate_docs
+        run: |
+          "$BIN/bazel" run //:generate_docs
         working-directory: ${{ github.workspace }}/docs
-      - name: Save the newly built book
+
+      - name: mdbook build root
+        run: |
+          "$BIN/mdbook" build
+        working-directory: ${{ github.workspace }}/docs/root
+        if: ${{ matrix.ref == 'main' }}
+
+      - name: mdbook build docs
+        run: |
+          "$BIN/mdbook" build
+        working-directory: ${{ github.workspace }}/docs
+
+      - name: Upload docs root
         uses: actions/upload-artifact@v4
         with:
-          name: "${{ matrix.ref }}"
+          name: ${{ matrix.ref }}-root
+          path: ${{ github.workspace }}/docs/root/book
+          if-no-files-found: error
+        if: ${{ github.event_name != 'pull_request' && matrix.ref == 'main' }}
+
+      - name: Upload docs/book
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ matrix.ref }}
           path: ${{ github.workspace }}/docs/book
           if-no-files-found: error
         if: ${{ github.event_name != 'pull_request' }}
-      - name: Build root
-        run: ${{ github.workspace }}/bin/mdbook build
-        if: ${{ matrix.ref == 'main' }}
-        working-directory: ${{ github.workspace }}/docs/root
-      - name: Save the newly built book
-        uses: actions/upload-artifact@v4
-        with:
-          name: "${{ matrix.ref }}-root"
-          path: ${{ github.workspace }}/docs/root/book
-          if-no-files-found: error
-        if: ${{ matrix.ref == 'main' && github.event_name != 'pull_request' }}
-  publish:
-    needs: pages
-    if: ${{ github.event_name != 'pull_request' }}
+
+  deploy:
     runs-on: ubuntu-latest
+    needs: build
+    if: ${{ github.event_name != 'pull_request' }}
+
+    defaults:
+      run:
+        shell: bash --noprofile --norc -euo pipefail {0}
+
+    env:
+      WORKSPACE: ${{ github.workspace }}
+
     steps:
-    - name: Fetch artifacts (first root then others so the ordering is correct)
-      uses: actions/download-artifact@v2
+      - name: Fetch artifacts (first root)
+        uses: actions/download-artifact@v4
         with:
           name: main-root
           path: ${{ github.workspace }}/docs/book
-    - name: Fetch artifacts (first root then others so the ordering is correct)
-      uses: actions/download-artifact@v2
+
+      - name: Fetch artifacts (then others)
+        uses: actions/download-artifact@v4
         with:
           path: ${{ github.workspace }}/docs/pages
+
       - name: Install pages
-      run: mv ${{ github.workspace }}/docs/pages/* ${{ github.workspace }}/docs/book/
+        run: mv "$WORKSPACE/docs/pages/"* "$WORKSPACE/docs/book/"
+
       - name: publish
-      uses: peaceiris/actions-gh-pages@v3
+        uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_branch: docs

.pre-commit-config.yaml

@@ -2,6 +2,11 @@
 # See https://pre-commit.com for more information
 # See https://pre-commit.com/hooks.html for more hooks
 repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-yaml
+
   - repo: https://github.com/keith/pre-commit-buildifier
     rev: 6.1.0.1
     hooks:
@@ -11,3 +16,21 @@ repos:
           - --warnings=all
       - id: buildifier-lint
         args: *args
+
+  - repo: https://github.com/mpalmer/action-validator
+    rev: v0.6.0
+    hooks:
+      - id: action-validator
+        files: >-
+          (?x)^(
+            .github/workflows/pages.yaml
+          )$
+
+  - repo: https://github.com/rhysd/actionlint
+    rev: v1.7.4
+    hooks:
+      - id: actionlint
+        files: >-
+          (?x)^(
+            .github/workflows/pages.yaml
+          )$