fix: change deploy workflow to match gohugo recs

reference docs:

https://gohugo.io/host-and-deploy/host-on-github-pages/

https://github.com/jmooring/hosting-github-pages-official-docker-image/blob/main/.github/workflows/hugo.yaml

Author: alee

.agent/working-memory/session.md

@@ -11,7 +11,7 @@
 
 - Workflow: `.github/workflows/gh-pages.yml`
 - Trigger: push to `develop` branch
-- Build: Hugo v0.159.1 (extended), Node.js 22, `npm ci`, `hugo --minify --gc`
+- Build: containerized via Docker Compose (`docker compose build hugo` + `docker compose run hugo hugo build --gc --minify`), mirroring local deployment toolchain and image
 - Deploy method: `actions/upload-pages-artifact` + `actions/deploy-pages` (OIDC, no branch write)
 - **No `main` branch is used for deployment.** The old `peaceiris/actions-gh-pages` approach that pushed to `main` has been replaced. The `main` branch is obsolete.
 - Required repo setting: Settings → Pages → Source must be **GitHub Actions** (not "Deploy from a branch").

.github/workflows/gh-pages.yml

@@ -4,6 +4,7 @@ on:
   push:
     branches:
       - develop
+  workflow_dispatch:
 
 # Required for GitHub Pages OIDC deployment
 permissions:
@@ -13,48 +14,60 @@ permissions:
 
 # Allow only one concurrent deployment; queue the next, cancel any in-between
 concurrency:
-  group: "pages"
+  group: pages
   cancel-in-progress: false
 
+defaults:
+  run:
+    shell: bash
+
 jobs:
   build:
     runs-on: ubuntu-latest
+    env:
+      HUGO_CACHEDIR: ./.hugo_cache
     steps:
-      - uses: actions/checkout@v4
+      - name: Checkout
+        uses: actions/checkout@v4
         with:
           fetch-depth: 0  # full history for Hugo .GitInfo / .Lastmod
 
-      - name: Read Hugo version from .env
-        id: hugo-version
-        run: |
-          . ./.env
-          echo "HUGO_VERSION=${HUGO_VERSION}" >> $GITHUB_OUTPUT
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v5
 
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: "22"
-          cache: 'npm'
+      - name: Configure Git
+        run: |
+          git config core.quotepath false
 
-      - name: Setup Hugo
-        uses: peaceiris/actions-hugo@v3
+      - name: Restore build cache
+        uses: actions/cache/restore@v4
         with:
-          # sync version with .env / Dockerfile
-          hugo-version: "${{ steps.hugo-version.outputs.HUGO_VERSION }}"
-          extended: true
+          path: ${{ env.HUGO_CACHEDIR }}
+          key: hugo-${{ runner.os }}-${{ github.run_id }}
+          restore-keys: |
+            hugo-${{ runner.os }}-
 
-      - name: Configure Pages
-        uses: actions/configure-pages@v5
-
-      - name: Install npm dependencies
-        run: npm ci
-
-      - name: Build Hugo site
+      - name: Build in Docker Compose
         env:
-          HUGO_ENV: "production"
-        run: hugo --minify --gc
+          BASE_URL: ${{ steps.pages.outputs.base_url }}
+        run: |
+          docker compose build --pull hugo
+          docker compose run --rm --no-deps \
+            --user "$(id -u):$(id -g)" \
+            -e HUGO_ENV=production \
+            -e HUGO_CACHEDIR="${HUGO_CACHEDIR}" \
+            -e BASE_URL="${BASE_URL}" \
+            hugo sh -lc 'git config --global --add safe.directory /src && git config --global core.quotepath false && hugo build --gc --minify --baseURL "${BASE_URL%/}/" --cacheDir "${HUGO_CACHEDIR}"'
+
+      - name: Save build cache
+        if: always()
+        uses: actions/cache/save@v4
+        with:
+          path: ${{ env.HUGO_CACHEDIR }}
+          key: hugo-${{ runner.os }}-${{ github.run_id }}
 
-      - name: Upload Pages artifact
+      - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
           path: ./public

README.md

@@ -25,7 +25,7 @@ The site is deployed to GitHub Pages via the workflow at `.github/workflows/gh-p
 
 ### How it works
 
-1. The `build` job checks out `develop`, installs Node.js 22 and Hugo (extended), runs `npm ci` and `hugo --minify --gc`, then uploads the built `public/` directory as a Pages artifact.
+1. The `build` job checks out `develop`, configures the Pages base URL, then builds the site inside the same Docker Compose `hugo` service used for local development (`docker compose build hugo` + `docker compose run hugo ...`). This mirrors local toolchain versions and container behavior in CI.
 2. The `deploy` job receives that artifact and publishes it directly to GitHub Pages via GitHub's OIDC-based Pages API (`actions/deploy-pages`).
 
 **No "built" branch is used.** The old approach pushed compiled HTML to a `main` branch using `peaceiris/actions-gh-pages`. That is no longer the case — the deployment artifact goes straight to GitHub's Pages infrastructure. The `main` branch (if it still exists in the remote) is a leftover and is no longer updated.