ci: add GitHub Pages pull request previews

.github/workflows/pages-deploy.yml

@@ -1,4 +1,4 @@
-# Direct Hugo build + GitHub Pages deploy (bypasses broken workflow_dispatch on build-test)
+# Build Hugo and publish the production site to the gh-pages branch.
 name: pages-deploy
 
 on:
@@ -8,9 +8,7 @@ on:
   workflow_dispatch:
 
 permissions:
-  contents: read
-  pages: write
-  id-token: write
+  contents: write
 
 concurrency:
   group: pages-deploy
@@ -21,7 +19,7 @@ defaults:
     shell: bash
 
 jobs:
-  build:
+  deploy:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -53,10 +51,6 @@ jobs:
       - name: Install Dart Sass
         run: sudo snap install dart-sass
 
-      - name: Setup Pages
-        id: pages
-        uses: actions/configure-pages@v6
-
       - name: Install Node.js dependencies
         run: "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true"
 
@@ -67,18 +61,12 @@ jobs:
         run: |
           hugo --gc --minify --baseURL "https://isaaclins.com/"
 
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v5
+      - name: Publish production site
+        uses: JamesIves/github-pages-deploy-action@v4
         with:
-          path: ./public
-
-  deploy:
-    needs: build
-    runs-on: ubuntu-latest
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    steps:
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v5
+          token: ${{ github.token }}
+          branch: gh-pages
+          folder: ./public
+          clean-exclude: pr-preview/
+          single-commit: false
+          force: false

.github/workflows/pr-preview.yml

@@ -0,0 +1,84 @@
+name: Deploy PR previews
+
+on:
+  pull_request:
+    branches:
+      - main
+    types:
+      - opened
+      - synchronize
+      - reopened
+      - closed
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: "pr-preview-${{ github.event.number }}"
+  cancel-in-progress: false
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  deploy-preview:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+        with:
+          submodules: recursive
+          fetch-depth: 0
+
+      - name: Read Hugo version
+        if: github.event.action != 'closed'
+        run: |
+          HUGO_VERSION="$(tr -d '[:space:]' < .hugo-version)"
+          if [[ ! "$HUGO_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "::error::Invalid Hugo version in .hugo-version: $HUGO_VERSION"
+            exit 1
+          fi
+          echo "HUGO_VERSION=$HUGO_VERSION" >> "$GITHUB_ENV"
+
+      - name: Install Hugo CLI
+        if: github.event.action != 'closed'
+        run: |
+          wget -O ${{ runner.temp }}/hugo.deb "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb"
+          sudo dpkg -i ${{ runner.temp }}/hugo.deb
+
+      - name: Verify Hugo Version
+        if: github.event.action != 'closed'
+        run: hugo version
+
+      - name: Enforce Hugo minimum version
+        if: github.event.action != 'closed'
+        run: python3 scripts/check-hugo-version.py
+
+      - name: Install Dart Sass
+        if: github.event.action != 'closed'
+        run: sudo snap install dart-sass
+
+      - name: Install Node.js dependencies
+        if: github.event.action != 'closed'
+        run: "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true"
+
+      - name: Build preview with Hugo
+        if: github.event.action != 'closed'
+        env:
+          HUGO_ENVIRONMENT: production
+          HUGO_ENV: production
+        run: |
+          hugo --gc --minify --baseURL "https://isaaclins.com/pr-preview/pr-${{ github.event.number }}/"
+
+      - name: Deploy or remove preview
+        uses: rossjrw/pr-preview-action@v1
+        with:
+          token: ${{ github.token }}
+          source-dir: ./public
+          preview-branch: gh-pages
+          pages-base-url: isaaclins.com
+          action: auto
+          wait-for-pages-deployment: false
+          qr-code: false

README.md

@@ -47,7 +47,16 @@ hugo --gc --minify     # production build into ./public
 - **build-test** — builds the site, validates the generated HTML with
   `html5validator`, and runs `cspell` on non-draft content for pushes to `main`
   and pull requests targeting `main`.
-- **pages-deploy** — builds and deploys to GitHub Pages on push to `main`.
+- **pages-deploy** — builds the production site and publishes it to the
+  `gh-pages` branch on push to `main`.
+- **PR previews** — builds each pull request targeting `main` and publishes it
+  at `https://isaaclins.com/pr-preview/pr-<number>/`. The pull request preview
+  workflow uses `rossjrw/pr-preview-action` and removes the preview when the
+  pull request closes.
+- GitHub Pages must be set to **Deploy from a branch**, using `gh-pages` and the
+  repository root. The site must keep [`static/CNAME`](static/CNAME) with the
+  exact contents `isaaclins.com`; Hugo copies it to `public/CNAME` so branch
+  deployments keep the custom domain.
 - Both Hugo workflows read the pinned version from [`.hugo-version`](.hugo-version)
   and enforce `config.toml`'s minimum with `scripts/check-hugo-version.py`;
   update the version file when upgrading Hugo.

static/CNAME

@@ -0,0 +1 @@
+isaaclins.com