fix: update htmltest sanity check for new deploy

Author: alee

.agent/working-memory/session.md

@@ -15,3 +15,11 @@
 - 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").
+
+## CI troubleshooting (updated 2026-03-29)
+
+- Hugo module/cache paths inside the container must resolve to absolute directories for the current CI image/version.
+- For Docker Compose workflows, use separate variables for host and container cache paths:
+	- host path for GitHub Actions cache: `./.hugo_cache`
+	- container path for Hugo `--cacheDir`: `/src/.hugo_cache`
+- Running the container as `--user "$(id -u):$(id -g)"` avoids root-owned workspace files, but it also means default cache locations like `/cache/modules` may be unwritable.

.github/workflows/gh-pages.yml

@@ -25,7 +25,8 @@ jobs:
   build:
     runs-on: ubuntu-latest
     env:
-      HUGO_CACHEDIR: ./.hugo_cache
+      HUGO_CACHE_HOST_DIR: ./.hugo_cache
+      HUGO_CACHE_CONTAINER_DIR: /src/.hugo_cache
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -43,7 +44,7 @@ jobs:
       - name: Restore build cache
         uses: actions/cache/restore@v4
         with:
-          path: ${{ env.HUGO_CACHEDIR }}
+          path: ${{ env.HUGO_CACHE_HOST_DIR }}
           key: hugo-${{ runner.os }}-${{ github.run_id }}
           restore-keys: |
             hugo-${{ runner.os }}-
@@ -54,17 +55,20 @@ jobs:
         run: |
           docker compose build --pull hugo
           docker compose run --rm --no-deps \
+            --entrypoint sh \
             --user "$(id -u):$(id -g)" \
+            -e HOME=/tmp \
+            -e npm_config_cache=/tmp/.npm \
             -e HUGO_ENV=production \
-            -e HUGO_CACHEDIR="${HUGO_CACHEDIR}" \
+            -e HUGO_CACHEDIR="${HUGO_CACHE_CONTAINER_DIR}" \
             -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}"'
+            hugo -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 }}
+          path: ${{ env.HUGO_CACHE_HOST_DIR }}
           key: hugo-${{ runner.os }}-${{ github.run_id }}
 
       - name: Upload artifact

.github/workflows/run-htmltest.yml

@@ -4,48 +4,43 @@ on:
     branches: [ "develop" ]
   pull_request:
     branches: [ "develop" ]
+  workflow_dispatch:
 
 jobs:
   htmltest:
     runs-on: ubuntu-latest
+    env:
+      HUGO_CACHE_HOST_DIR: ./.hugo_cache
+      HUGO_CACHE_CONTAINER_DIR: /src/.hugo_cache
     steps:
       - uses: actions/checkout@v4
-
-      - name: Read .env hugo version
-        id: hugo-version
-        run: |
-          . ./.env
-          echo "::set-output name=HUGO_VERSION::${HUGO_VERSION}"
-          echo "::set-output name=DOCSY_VERSION::${DOCSY_VERSION}"
-
-      - name: Add hugo nodejs dependencies
-        uses: actions/setup-node@v4
         with:
-          node-version: "18"
-          cache: 'npm'
+          fetch-depth: 0
 
-      - name: Setup Hugo
-        uses: peaceiris/actions-hugo@v3
-        with:
-          # sync versions with docker-compose .env ala
-          # https://github.com/marketplace/actions/hugo-setup#%EF%B8%8F-read-hugo-version-from-file
-          hugo-version: "${{ steps.hugo-version.outputs.HUGO_VERSION }}"
-          extended: true
-
-      - name: Build Hugo site
+      - name: Build Hugo site in Docker Compose
         env:
           HUGO_ENV: "production"
         run: |
-          npm install
-          hugo --minify --gc -d $GITHUB_WORKSPACE/dist
+          docker compose build --pull hugo
+          docker compose run --rm --no-deps \
+            --entrypoint sh \
+            --user "$(id -u):$(id -g)" \
+            -e HOME=/tmp \
+            -e npm_config_cache=/tmp/.npm \
+            -e HUGO_CACHEDIR="${HUGO_CACHE_CONTAINER_DIR}" \
+            -e HUGO_ENV="${HUGO_ENV}" \
+            hugo -lc 'git config --global --add safe.directory /src && git config --global core.quotepath false && hugo build --gc --minify --cacheDir "${HUGO_CACHEDIR}" -d /src/dist'
+
       - name: run htmltest
         continue-on-error: true
         uses: wjdp/htmltest-action@master
         with:
           config: .htmltest.yml
+
       - name: archive htmltest results
+        if: always()
         uses: actions/upload-artifact@v4
         with:
           name: htmltest-report
-          path: tmp/.htmltest/htmltest.log
+          path: tmp/.htmltest/
           retention-days: 5

Dockerfile

@@ -10,7 +10,7 @@ USER root
 RUN git config --global --add safe.directory /src
 
 # Install Node.js and npm for PostCSS (required by Docsy)
-RUN apk add --no-cache nodejs npm
+RUN apk add --no-cache nodejs npm go
 
 # Install front-end tooling.
 # Layer is invalidated only when package.json or package-lock.json changes.

hugo.yaml

@@ -48,10 +48,8 @@ module:
   # mount ISSUE_TEMPLATE to content/issue_templates to re-use the templates in the site
     - source: "content/en"
       target: "content"
-      lang: "en"
     - source: ".github/ISSUE_TEMPLATE"
       target: "content/issue_templates"
-      lang: "en"
 
 # Configure how URLs look like per section.
 permalinks: