From 07cfdd7e8f9647780a5ddfd1d0508084964e97be Mon Sep 17 00:00:00 2001
From: anngdinh <72872427+anngdinh@users.noreply.github.com>
Date: Mon, 15 Jun 2026 09:02:37 +0000
Subject: [PATCH 1/2] ci(docs): add per-PR documentation previews

Build the MkDocs site on pull requests and publish it to
gh-pages/pr-preview/pr-<N>/ via rossjrw/pr-preview-action, posting the
preview link as a PR comment and cleaning it up when the PR closes.

Coexists with mike (separate gh-pages subtrees). Only deploys for
same-repo PRs since fork PRs get a read-only token.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .github/workflows/docs-preview.yml | 56 ++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)
 create mode 100644 .github/workflows/docs-preview.yml

diff --git a/.github/workflows/docs-preview.yml b/.github/workflows/docs-preview.yml
new file mode 100644
index 0000000..3eb191d
--- /dev/null
+++ b/.github/workflows/docs-preview.yml
@@ -0,0 +1,56 @@
+name: Deploy Documentation Preview
+
+# Per-PR docs preview. Each PR is built and published to gh-pages under
+# pr-preview/pr-<N>/ and a link is posted as a PR comment; the preview is
+# removed automatically when the PR is closed.
+#
+# Coexists with mike: mike only manages the version folders + versions.json,
+# pr-preview-action only manages the pr-preview/ umbrella, so they don't clash.
+#
+# Note: uses the `pull_request` event, so previews only deploy for PRs from
+# branches in this repo. Fork PRs get a read-only token and will skip the deploy.
+
+on:
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - synchronize
+      - closed
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'Pipfile'
+      - '.github/workflows/docs-preview.yml'
+
+concurrency: docs-preview-${{ github.event.pull_request.number }}
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  deploy-preview:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        if: github.event.action != 'closed'
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        if: github.event.action != 'closed'
+        run: pip install pipenv && pipenv install
+
+      - name: Build docs
+        if: github.event.action != 'closed'
+        run: pipenv run mkdocs build --site-dir site
+
+      - name: Deploy preview
+        uses: rossjrw/pr-preview-action@v1
+        with:
+          source-dir: site
+          umbrella-dir: pr-preview

From 3c732d732fed3a1d494ead6712553dda6dfceddf Mon Sep 17 00:00:00 2001
From: anngdinh <72872427+anngdinh@users.noreply.github.com>
Date: Mon, 15 Jun 2026 09:08:16 +0000
Subject: [PATCH 2/2] ci(docs): force Node 24 for pr-preview nested actions

pr-preview-action (even v1.8.1) still pins Node 20 actions internally.
Set FORCE_JAVASCRIPT_ACTIONS_TO_NODE24 to silence the deprecation warning;
no-op once Node 24 is the runner default.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .github/workflows/docs-preview.yml | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/.github/workflows/docs-preview.yml b/.github/workflows/docs-preview.yml
index 3eb191d..7a2644d 100644
--- a/.github/workflows/docs-preview.yml
+++ b/.github/workflows/docs-preview.yml
@@ -32,6 +32,11 @@ permissions:
 jobs:
   deploy-preview:
     runs-on: ubuntu-latest
+    # pr-preview-action still pins Node 20 nested actions (JamesIves/github-pages-deploy-action,
+    # marocchino/sticky-pull-request-comment). Opt them into Node 24 now to silence the deprecation
+    # warning; becomes a no-op once Node 24 is the runner default.
+    env:
+      FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
     steps:
       - uses: actions/checkout@v6