From 9e409a628df0695f798728de1358dba203ba9f28 Mon Sep 17 00:00:00 2001
From: Jeff Bailey <776901+jeffabailey@users.noreply.github.com>
Date: Tue, 17 Mar 2026 22:32:09 -0700
Subject: [PATCH 1/2] fix(pages): merge pr-* from gh-pages into deploy artifact
 so PR previews are served

Made-with: Cursor
---
 .github/workflows/mdbook.yml | 88 ++++++++++++++++++++++++++++--------
 1 file changed, 70 insertions(+), 18 deletions(-)

diff --git a/.github/workflows/mdbook.yml b/.github/workflows/mdbook.yml
index c6a2fac..04e5194 100644
--- a/.github/workflows/mdbook.yml
+++ b/.github/workflows/mdbook.yml
@@ -1,58 +1,110 @@
-# Workflow for building and deploying a mdBook site to GitHub Pages
-#
-# To get started with mdBook see: https://rust-lang.github.io/mdBook/index.html
+# Workflow for building and deploying a mdBook site to GitHub Pages.
+# Serves the main book at / and PR previews at /pr-<number>/ by merging
+# pr-* directories from the gh-pages branch (pushed by mdbook-pr-preview.yml)
+# into the deployed artifact. Works with Pages source "GitHub Actions".
 #
+# See: https://rust-lang.github.io/mdBook/index.html
 name: Deploy mdBook site to Pages
 
 on:
-  # Runs on pushes targeting the default branch
   push:
     branches: ["main"]
-
-  # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
-# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
 permissions:
   contents: read
   pages: write
   id-token: write
 
-# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
-# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
 concurrency:
   group: "pages"
   cancel-in-progress: false
 
 jobs:
-  # Build job
   build:
     runs-on: ubuntu-latest
     env:
-      MDBOOK_VERSION: 0.4.52
-      MDBOOK_MERMAID_VERSION: 0.10.0
       CARGO_HOME: ${{ github.workspace }}/.cargo
       RUSTUP_HOME: ${{ github.workspace }}/.rustup
     steps:
       - uses: actions/checkout@v4
+
+      - name: Cache Cargo registry and git index
+        uses: actions/cache@v4
+        with:
+          path: |
+            ${{ env.CARGO_HOME }}/registry
+            ${{ env.CARGO_HOME }}/git
+          key: ${{ runner.os }}-cargo-registry-${{ hashFiles('scripts/install-mdbook.sh') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-registry-
+
+      - name: Cache Rust toolchains
+        uses: actions/cache@v4
+        with:
+          path: |
+            ${{ env.RUSTUP_HOME }}/toolchains
+            ${{ env.RUSTUP_HOME }}/update-hashes
+          key: ${{ runner.os }}-rust-toolchain-${{ hashFiles('scripts/install-mdbook.sh') }}
+          restore-keys: |
+            ${{ runner.os }}-rust-toolchain-
+
+      - name: Cache installed mdBook binaries
+        id: mdbook-cache
+        uses: actions/cache@v4
+        with:
+          path: |
+            ${{ env.CARGO_HOME }}/bin
+          key: ${{ runner.os }}-mdbook-bin-${{ hashFiles('scripts/install-mdbook.sh') }}
+          restore-keys: |
+            ${{ runner.os }}-mdbook-bin-
+
       - name: Install mdBook
+        if: steps.mdbook-cache.outputs.cache-hit != 'true'
         run: bash scripts/install-mdbook.sh
         env:
           REPO_ROOT: ${{ github.workspace }}
-          MDBOOK_VERSION: ${{ env.MDBOOK_VERSION }}
-          MDBOOK_MERMAID_VERSION: ${{ env.MDBOOK_MERMAID_VERSION }}
-      - name: Setup Pages
-        id: pages
-        uses: actions/configure-pages@v5
+
+      - name: Add Cargo bin to PATH
+        run: echo "${CARGO_HOME}/bin" >> "$GITHUB_PATH"
+
       - name: Build with mdBook
         run: ${{ env.CARGO_HOME }}/bin/mdbook build
+
+      - name: Merge PR previews from gh-pages into artifact
+        run: |
+          set -e
+          echo "Fetching gh-pages branch..."
+          git fetch origin gh-pages 2>/dev/null || true
+          if ! git rev-parse -q origin/gh-pages >/dev/null 2>&1; then
+            echo "No gh-pages branch found; skipping PR preview merge."
+            exit 0
+          fi
+          PR_DIRS=$(git ls-tree -d --name-only origin/gh-pages 2>/dev/null | grep -E '^pr-[0-9]+$' || true)
+          if [ -z "$PR_DIRS" ]; then
+            echo "No pr-* directories on gh-pages; skipping."
+            exit 0
+          fi
+          echo "Merging PR preview dirs: $PR_DIRS"
+          for d in $PR_DIRS; do
+            echo "  -> merging $d"
+            git archive origin/gh-pages "$d" | tar -x -C book
+          done
+          echo "Done. Contents of book/ after merge:"
+          ls -la book/ | head -30
+
       - name: Upload artifact
+        if: ${{ !env.ACT }}
         uses: actions/upload-pages-artifact@v3
         with:
           path: ./book
 
-  # Deployment job
+      - name: Confirm local act build
+        if: ${{ env.ACT }}
+        run: echo "Local act run: mdBook build completed; skipping upload."
+
   deploy:
+    if: ${{ !env.ACT }}
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}

From cc3373221d845b5899840fcd750284c1313ebfe7 Mon Sep 17 00:00:00 2001
From: Jeff Bailey <776901+jeffabailey@users.noreply.github.com>
Date: Tue, 17 Mar 2026 22:33:58 -0700
Subject: [PATCH 2/2] fix: quote run value to fix YAML syntax (exclamation in
 string)

Made-with: Cursor
---
 .github/workflows/mdbook.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/mdbook.yml b/.github/workflows/mdbook.yml
index 04e5194..eb8c52b 100644
--- a/.github/workflows/mdbook.yml
+++ b/.github/workflows/mdbook.yml
@@ -101,7 +101,7 @@ jobs:
 
       - name: Confirm local act build
         if: ${{ env.ACT }}
-        run: echo "Local act run: mdBook build completed; skipping upload."
+        run: 'echo "Local act run: mdBook build completed; skipping upload."'
 
   deploy:
     if: ${{ !env.ACT }}