From 65a60a4723d26acea5fdc7dd34e0536063d65c4b Mon Sep 17 00:00:00 2001
From: Mladen Milankovic <developer@mmlado.com>
Date: Mon, 14 Sep 2026 17:15:41 +0200
Subject: [PATCH] Publish the site from a gh-pages branch

Push the built HTML and PDF to a gh-pages branch with
peaceiris/actions-gh-pages, the way the other Cryptnox documentation
repositories do, so the generated site stays out of the source branch.

Pages on this repository is set to serve the main branch, which made
every push race GitHub's own Jekyll build against the Actions
deployment: whichever finished last was served. The workflow now points
the Pages source at gh-pages after publishing, and fails with an
instruction for an administrator if its token is not allowed to.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .github/workflows/deploy.yml | 61 ++++++++++++++++++++++++------------
 1 file changed, 41 insertions(+), 20 deletions(-)

diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
index 2686a89..805eb61 100644
--- a/.github/workflows/deploy.yml
+++ b/.github/workflows/deploy.yml
@@ -1,4 +1,4 @@
-name: Deploy Sphinx to GitHub Pages
+name: Build and deploy documentation
 
 on:
   push:
@@ -7,17 +7,18 @@ on:
     branches: [main]
   workflow_dispatch:
 
+# contents: write lets the publish step push to the gh-pages branch;
+# pages: write lets the last step point GitHub Pages at that branch.
 permissions:
-  contents: read
+  contents: write
   pages: write
-  id-token: write
 
 concurrency:
   group: "pages"
   cancel-in-progress: false
 
 jobs:
-  build:
+  build-docs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -30,7 +31,7 @@ jobs:
         run: pip install -r requirements.txt
 
       - name: Build Sphinx
-        run: sphinx-build -W -b html docs/source _site
+        run: sphinx-build -W -b html docs/source docs/_build/html
 
       - name: Install LaTeX for PDF
         run: |
@@ -42,20 +43,40 @@ jobs:
       - name: Build PDF (pdflatex)
         run: |
           sphinx-build -M latexpdf docs/source docs/_build
-          cp docs/_build/latex/cryptnox-readers.pdf _site/cryptnox-readers.pdf
+          cp docs/_build/latex/cryptnox-readers.pdf docs/_build/html/cryptnox-readers.pdf
 
-      - uses: actions/upload-pages-artifact@v3
+      # Publish only from main or a manual run, never from a pull request build.
+      - name: Publish to the gh-pages branch
+        if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
+        uses: peaceiris/actions-gh-pages@v4
         with:
-          path: _site
-
-  deploy:
-    # Only deploy on push to main or manual trigger — not on PR builds
-    if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    runs-on: ubuntu-latest
-    needs: build
-    steps:
-      - id: deployment
-        uses: actions/deploy-pages@v4
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/_build/html
+          publish_branch: gh-pages
+          allow_empty_commit: false
+          keep_files: false
+          force_orphan: false
+          enable_jekyll: false
+
+      # GitHub Pages must serve the gh-pages branch, not the source branch.
+      # Set it here so the site does not depend on a manual setting; if the
+      # workflow token is not allowed to, fail with the instruction instead.
+      - name: Point GitHub Pages at the gh-pages branch
+        if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          current=$(gh api "repos/${GITHUB_REPOSITORY}/pages" \
+                      --jq '"\(.build_type):\(.source.branch // "")"' 2>/dev/null || echo unknown)
+          echo "Pages source is currently: ${current}"
+          if [ "${current}" = "legacy:gh-pages" ]; then
+            echo "Already serving from the gh-pages branch."
+            exit 0
+          fi
+          if gh api -X PUT "repos/${GITHUB_REPOSITORY}/pages" \
+               -f build_type=legacy -f 'source[branch]=gh-pages' -f 'source[path]=/'; then
+            echo "Pages source set to the gh-pages branch."
+          else
+            echo "::error::The workflow token may not change the Pages source. A repository admin must set Settings > Pages > Source to 'Deploy from a branch', branch 'gh-pages', folder '/ (root)'."
+            exit 1
+          fi