From 619a74576b6468bd1e47a8ba5e1b920437a96e59 Mon Sep 17 00:00:00 2001
From: NullSablex <244216261+NullSablex@users.noreply.github.com>
Date: Mon, 18 May 2026 13:00:42 -0300
Subject: [PATCH] Migrate Pages deploy from gh-pages branch to
 actions/deploy-pages

GitHub Pages was switched to the workflow-based source (build_type=workflow)
but the docs.yml job kept calling `mkdocs gh-deploy --force --clean`, which
only writes to the gh-pages branch that the new Pages source no longer reads.
Result: every Docs run was green while the live site stayed on the old
Jekyll render of master.

Rewrite the deploy job to use the proper Pages deployment actions:

- build: still runs mkdocs build --strict on push and PR. On master push,
  also uploads the rendered site/ as a Pages artifact via
  actions/upload-pages-artifact@v5.
- deploy: replaces the `mkdocs gh-deploy` step with actions/deploy-pages@v5.
  Adds the required `pages: write` + `id-token: write` permissions and the
  `environment: github-pages` declaration GitHub requires for OIDC-signed
  Pages deployments.
- concurrency: group:pages, cancel-in-progress:false prevents racing
  deployments without aborting one already in flight.

The gh-pages branch is no longer touched and can be deleted after the first
successful workflow-based deploy.
---
 .github/workflows/docs.yml | 42 +++++++++++++++++++++++---------------
 1 file changed, 25 insertions(+), 17 deletions(-)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 7df6cbd..da5c758 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -20,6 +20,13 @@ on:
 permissions:
   contents: read
 
+# Only one Pages deployment can run at a time. Cancelling a queued
+# deployment in favour of a newer one is fine; cancelling one already
+# in flight would orphan a partial deploy, so we let it finish.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
 jobs:
   build:
     name: Build site
@@ -41,27 +48,28 @@ jobs:
       - name: Strict build (fails on warnings)
         run: mkdocs build --strict
 
+      # Upload the generated site so the deploy job (or anyone debugging
+      # a PR) can grab it. Uses the dedicated Pages artifact format.
+      - name: Upload Pages artifact
+        if: github.event_name == 'push' && github.ref == 'refs/heads/master'
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: site
+
   deploy:
     name: Deploy to GitHub Pages
     needs: build
     if: github.event_name == 'push' && github.ref == 'refs/heads/master'
     runs-on: ubuntu-latest
-    # `mkdocs gh-deploy` pushes to the gh-pages branch.
+    # `actions/deploy-pages` needs `pages: write` to publish and
+    # `id-token: write` for OIDC verification of the artifact.
     permissions:
-      contents: write
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
     steps:
-      - uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
-
-      - uses: actions/setup-python@v6
-        with:
-          python-version: '3.x'
-          cache: pip
-          cache-dependency-path: docs/requirements.txt
-
-      - name: Install MkDocs and theme
-        run: pip install -r docs/requirements.txt
-
-      - name: Deploy
-        run: mkdocs gh-deploy --force --clean
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5