build: make Hugo validation reproducible

Author: kevinten10

.dockerignore

@@ -0,0 +1,9 @@
+.git
+.github
+.idea
+.superpowers
+docs
+node_modules
+public
+resources
+themes/docsy/node_modules

CLAUDE.md

@@ -51,15 +51,20 @@ hugo --gc
 HUGO_ENV="production" hugo --gc
 ```
 
+The Makefile and npm scripts automatically use the pinned official Hugo
+container when `hugo` is not installed locally.
+
 ### Docker (Alternative)
 
 ```bash
-# Run using Docker Compose
-docker-compose up
-
-# Or build and run manually
-docker build -t capa-docs .
-docker run -p 1313:1313 -v $(pwd):/src capa-docs server
+# Build the pinned official Hugo image
+docker build --build-arg HUGO_VERSION=0.145.0 -t capa-docs .
+
+# Serve the local checkout (install npm dependencies first)
+npm ci
+npm --prefix themes/docsy install
+docker run --rm -p 1313:1313 -v "$(pwd):/project" capa-docs \
+  server -D --bind 0.0.0.0
 ```
 
 ## Architecture

Dockerfile

@@ -1,3 +1,5 @@
-FROM klakegg/hugo:ext-alpine
+ARG HUGO_VERSION=0.145.0
+FROM ghcr.io/gohugoio/hugo:v${HUGO_VERSION}
 
-RUN apk add git
+WORKDIR /project
+EXPOSE 1313

Makefile

@@ -1,7 +1,7 @@
 # Capa.io Makefile
 # Simplified build commands for Hugo documentation site
 
-.PHONY: dev build clean deploy help submodule
+.PHONY: dev build check clean deploy help submodule
 
 # Default target
 .DEFAULT_GOAL := help
@@ -12,15 +12,19 @@ submodule:
 
 # Development server with drafts
 dev:
-	hugo server -D
+	./scripts/hugo.sh server -D
 
 # Development server binding to all interfaces
 dev-all:
-	hugo server -D --bind 0.0.0.0
+	./scripts/hugo.sh server -D --bind 0.0.0.0
 
 # Production build
 build:
-	HUGO_ENV="production" hugo --gc --minify
+	HUGO_ENV="production" ./scripts/hugo.sh --gc --minify
+
+# Validate all pages without changing generated site files
+check:
+	HUGO_ENV="production" HUGO_READ_ONLY=1 ./scripts/hugo.sh --gc --minify --renderToMemory --noBuildLock
 
 # Clean build artifacts
 clean:
@@ -49,6 +53,7 @@ help:
 	@echo "  make dev        - Run development server with drafts"
 	@echo "  make dev-all    - Run dev server binding to all interfaces"
 	@echo "  make build      - Build production site (outputs to docs/)"
+	@echo "  make check      - Validate the production site without writing output"
 	@echo "  make clean      - Remove build artifacts"
 	@echo "  make deploy     - Build and deploy to GitHub Pages"
 	@echo "  make link-check - Check for broken links"

docs/maintenance/2026-06-27-capa-io-triage.md

@@ -16,6 +16,8 @@
 - Migrated deprecated Docsy settings, removed the fake Universal Analytics ID, and removed a duplicate blog menu declaration.
 - Scoped gitleaks away from the pinned Docsy submodule, whose upstream search documentation contains example keys.
 - Updated checkout, Node setup, Hugo, and Pages actions to their current Node 24-based major versions; the build runtime now uses Node 22 to satisfy Docsy's engine requirement.
+- Replaced the unmaintained Hugo-on-Alpine image with the version-pinned official Hugo image and documented the working container mount path.
+- Added a local Hugo wrapper so validation falls back to a read-only container when Hugo is not installed.
 
 ## Validation
 

package-lock.json

@@ -6,15 +6,15 @@
   "scripts": {
     "dev": "make dev",
     "build": "make build",
-    "lint": "make build",
-    "test": "make build"
+    "lint": "make check",
+    "test": "make check"
   },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/capa-cloud/capa.io.git"
   },
   "author": "",
-  "license": "ISC",
+  "license": "Apache-2.0",
   "bugs": {
     "url": "https://github.com/capa-cloud/capa.io/issues"
   },

package.json

@@ -0,0 +1,33 @@
+#!/usr/bin/env sh
+set -eu
+
+if command -v hugo >/dev/null 2>&1; then
+  exec hugo "$@"
+fi
+
+if ! command -v docker >/dev/null 2>&1; then
+  echo "Hugo 0.145.0 or Docker is required." >&2
+  exit 127
+fi
+
+project_dir=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
+hugo_image=${HUGO_IMAGE:-ghcr.io/gohugoio/hugo:v0.145.0}
+
+if [ "${HUGO_READ_ONLY:-0}" = "1" ]; then
+  exec docker run --rm \
+    --user "$(id -u):$(id -g)" \
+    --env HOME=/tmp \
+    --env HUGO_CACHEDIR=/tmp/hugo-cache \
+    --env HUGO_ENV \
+    --volume "$project_dir:/project:ro" \
+    --tmpfs "/project/resources:uid=$(id -u),gid=$(id -g)" \
+    "$hugo_image" "$@"
+fi
+
+exec docker run --rm \
+  --user "$(id -u):$(id -g)" \
+  --env HOME=/tmp \
+  --env HUGO_CACHEDIR=/tmp/hugo-cache \
+  --env HUGO_ENV \
+  --volume "$project_dir:/project" \
+  "$hugo_image" "$@"