fix: adjust approach with gh-pages

Author: jeffabailey

.github/workflows/mdbook.yml

@@ -1,36 +1,34 @@
 # Workflow for building and deploying a mdBook site to GitHub Pages.
-# Publishes to the gh-pages branch so PR previews (pr-<number>/) from
-# mdbook-pr-preview.yml are served from the same branch. Set Pages source
-# to "Deploy from a branch" → gh-pages, folder / (root).
+# 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:
 
-# Push to gh-pages so PR previews (mdbook-pr-preview) are served from the same branch.
-# Repository Settings → Pages → Source: Deploy from a branch → gh-pages / (root).
 permissions:
-  contents: write
+  contents: read
+  pages: write
+  id-token: write
 
 concurrency:
   group: "pages"
   cancel-in-progress: false
 
 jobs:
-  build-and-deploy:
+  build:
     runs-on: ubuntu-latest
     env:
       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:
@@ -60,24 +58,46 @@ jobs:
           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 }}
+
       - 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: Deploy to gh-pages (root)
+
+      - name: Merge PR previews from gh-pages into artifact
+        run: |
+          git fetch origin gh-pages 2>/dev/null || true
+          if git rev-parse -q origin/gh-pages >/dev/null 2>&1; then
+            for d in $(git ls-tree -d --name-only origin/gh-pages 2>/dev/null | grep -E '^pr-[0-9]+$'); do
+              git archive origin/gh-pages "$d" | tar -x -C book
+            done
+          fi
+
+      - name: Upload artifact
         if: ${{ !env.ACT }}
-        uses: peaceiris/actions-gh-pages@v4
+        uses: actions/upload-pages-artifact@v3
         with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_branch: gh-pages
-          publish_dir: ./book
-          keep_files: true
+          path: ./book
+
       - name: Confirm local act build
         if: ${{ env.ACT }}
-        run: |
-          echo "Local act run: mdBook build completed; skipping gh-pages deploy."
+        run: echo "Local act run: mdBook build completed; skipping upload."
+
+  deploy:
+    if: ${{ !env.ACT }}
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4