From d1288aa623c27aa1ba83fedeeb2768329e31bea2 Mon Sep 17 00:00:00 2001
From: Stephen Waits <steve@waits.net>
Date: Wed, 6 May 2026 08:58:57 -0600
Subject: [PATCH] ci(docs): re-enable GitHub Pages deploy
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Pages is now enabled on the repo (Settings → Pages → 'Build and
deployment: GitHub Actions'), so the workflow can use the standard
configure-pages → upload-pages-artifact → deploy-pages chain
without needing the GITHUB_TOKEN to enable Pages itself.

PR builds run the build job (catches mdbook breakage) but skip the
deploy job, so PRs don't republish the live site.
---
 .github/workflows/docs.yml | 32 +++++++++++++++++++++++---------
 1 file changed, 23 insertions(+), 9 deletions(-)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 556fbae..34b3990 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -10,6 +10,14 @@ on:
 
 permissions:
   contents: read
+  pages: write
+  id-token: write
+
+# Only one Pages deploy at a time. Don't cancel a running deploy
+# (otherwise we can leave the Pages site partially updated).
+concurrency:
+  group: pages
+  cancel-in-progress: false
 
 jobs:
   build:
@@ -27,15 +35,21 @@ jobs:
         run: |
           cd docs/book
           mdbook build
-      - name: Upload book as artifact
-        uses: actions/upload-artifact@v4
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v3
         with:
-          name: book
           path: target/book
-          if-no-files-found: error
-          retention-days: 14
 
-  # GitHub Pages deployment is intentionally not in this workflow.
-  # Once Pages is enabled on the repo (Settings → Pages → Build and
-  # deployment: GitHub Actions), this file can grow a `deploy` job
-  # using actions/configure-pages + actions/deploy-pages.
+  deploy:
+    name: Deploy to GitHub Pages
+    # Only deploy on pushes to main / tag pushes / manual runs.
+    # PR builds get the build-and-upload step but no deploy.
+    if: github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4