Move to Hugo v0.169.0 and the latest site-commons

.agents/tasks/hugo-0-169-upgrade.md

@@ -0,0 +1,67 @@
+---
+slug: hugo-0-169-upgrade
+branch: hugo-0.169
+owner: claude
+status: in-review
+started: 2026-10-30
+---
+
+## Goal
+
+The site builds and deploys on Hugo v0.169.0 with the latest `site-commons`,
+and CI checks links with the same Hugo version.
+
+## Context
+
+- SpineEventEngine/documentation#89 — upgrade Hugo to v0.169.0 (meta-issue;
+  also `documentation` and `site-commons`).
+- SpineEventEngine/documentation#92 — Hugo v0.162.0+ rejects `text/html` content
+  files. The full-screen architecture diagram that `documentation/docs` brings in
+  is one. Hugo ignores `security` set in an imported module, so the setting must
+  be in this site's own config.
+- The latest `site-commons` (`b79100d8a139`) declares
+  `module.hugoVersion.min = '0.169.0'` and needs Go 1.27.3, so it cannot land
+  without the Hugo bump.
+- `.github/workflows/check-links.yml` comes from `config`, which still pins
+  `HUGO_VERSION: 0.161.1`. Bumping it here is needed for CI; SpineEventEngine/config#823
+  makes the same bump there, or the next `./config/pull` reverts it.
+- The `documentation` side is SpineEventEngine/documentation#94, merged. It changes
+  only `docs/_preview`, a separate Go module, so the `documentation/docs` content
+  that this site imports is the same.
+
+## Plan
+
+- [x] Allow HTML content in `site/config/_default/hugo.toml` (documentation#92).
+- [x] `hugo mod get -u github.com/SpineEventEngine/site-commons` in `site/`.
+- [x] Bump `HUGO_VERSION` to `0.169.0` in `gh-pages.yml` and `check-links.yml`.
+- [x] Update Hugo and Go prerequisites in `README.md` and `docs/project.md`.
+- [x] Build with v0.169.0: `hugo --minify` and `hugo -e development`,
+  no errors and no new warnings.
+- [x] Check the full-screen diagram page: script and PDF.
+- [x] Check that CI's older Go fetches Go 1.27.3 by itself.
+- [x] Run the pre-PR checklist; open the PR.
+- [x] Update `github.com/SpineEventEngine/documentation/docs` to `documentation` `master`.
+
+## Log
+
+- 2026-10-30 — drafted and started (run delegated by the `documentation` session).
+- 2026-10-30 — both builds pass on v0.169.0; the only warning is the theme's
+  LibSass deprecation. The full-screen diagram page renders with its script and
+  the PDF. Its one console error, `Cannot read properties of null (reading '__k')`,
+  is on live spine.io too.
+- 2026-10-30 — compared with the old theme on v0.169.0: pages change only as
+  site-commons#37 intends (code palettes bundled into `main.css`, no
+  `/code-theme/*.css`, the theme falls back to the system preference), plus
+  trimmed whitespace. The code-theme toggle switches the palettes.
+- 2026-10-30 — `gh-pages.yml` sets up no Go. With Go 1.26.4 and an empty module
+  cache, `go` downloads Go 1.27.3 by itself (`GOTOOLCHAIN=auto`) and the build passes.
+- 2026-10-30 — pre-PR: `review-docs` approves; its nit on the `allowContent`
+  comment is applied. Link check: the Lychee run passes, but, as in `documentation`,
+  it extracts only the `<head>` URLs because of the inline jQuery block in every
+  page's `<head>`. CI has the same blind spot. With that block stripped, 10 URLs
+  are broken, the same on `master`: 9 in `validation/docs` and a Gitter link that
+  now redirects. None comes from this branch.
+- 2026-10-30 — `documentation/docs` moved to `3045fa4` (after documentation#94).
+  Only the pinned version changes: the extracted module is identical, and so is the
+  built site, apart from the random IDs of cloaked e-mail addresses.
+  `validation/docs` stays where it was.

.github/workflows/check-links.yml

@@ -12,7 +12,7 @@ on:
   workflow_dispatch:
 
 env:
-  HUGO_VERSION: 0.161.1
+  HUGO_VERSION: 0.169.0
   LYCHEE_RELEASE: "lychee-x86_64-unknown-linux-gnu.tar.gz"
   LYCHEE_VERSION_TAG: "lychee-v0.24.2"
   # SHA256 of the above tarball, pinned at download time. Update alongside

.github/workflows/gh-pages.yml

@@ -10,7 +10,7 @@ on:
   workflow_dispatch:
 
 env:
-  HUGO_VERSION: 0.161.1
+  HUGO_VERSION: 0.169.0
 
 jobs:
   deploy:

README.md

@@ -18,9 +18,9 @@ as a Hugo Module. This repository does not invoke `embed-code` itself.
 ## Prerequisites
 
 1. JDK 17+.
-2. [Go][go] `1.22` or newer.
+2. [Go][go] `1.27.3` or newer (matches `site/go.mod`).
 3. [Node.js][nodejs] `18+`.
-4. [Hugo Extended][hugo-quick-start] in version `v0.161.1` or higher.
+4. [Hugo Extended][hugo-quick-start] in version `v0.169.0` or higher.
 
 ## Configuration
 

docs/project.md

@@ -44,7 +44,7 @@ wrapper only** — no JVM compilation happens here.
 
 ## Constraints & guardrails
 
-- **Hugo Extended version is pinned.** Use `v0.161.1` or higher of the
+- **Hugo Extended version is pinned.** Use `v0.169.0` or higher of the
   *Extended* build. A mismatched/non-extended Hugo will break the theme
   pipeline and SCSS.
 - **The `config/` submodule is pinned to a specific commit.** Do not bump

site/config/_default/hugo.toml

@@ -36,6 +36,11 @@ disableKinds = ['taxonomy', 'term']
   id = '38b1283993fe8d87c0678be39b07ada2'
 
 [security]
+  # Since v0.162.0, Hugo denies HTML and Org mode content files by default. The full-screen
+  # architecture diagram that `documentation/docs` brings in is an HTML file, so HTML is allowed;
+  # Org mode stays denied. Hugo ignores the `security` settings of an imported module, so this
+  # setting has to be in the site config.
+  allowContent = ['! ^text/org$']
   [security.exec]
     osEnv = ['(?i)^(PATH|PATHEXT|APPDATA|TMP|TEMP|TERM|HOME)$']
   # Hugo 0.161.0+ runs PostCSS under Node's --permission sandbox, which blocks

site/go.mod

@@ -1,10 +1,10 @@
 module github.com/SpineEventEngine/SpineEventEngine.github.io
 
-go 1.22.0
+go 1.27.3
 
 require (
-	github.com/SpineEventEngine/documentation/docs v0.0.0-20261002133928-aeca7bbbea14 // indirect
-	github.com/SpineEventEngine/site-commons v0.0.0-20261001182820-d2b63aedd0f4 // indirect
+	github.com/SpineEventEngine/documentation/docs v0.0.0-20261030164337-3045fa4e0dd6 // indirect
+	github.com/SpineEventEngine/site-commons v0.0.0-20261030153256-b79100d8a139 // indirect
 	github.com/SpineEventEngine/validation/docs v0.0.0-20260902132507-6465029c83b9 // indirect
 	github.com/gohugoio/hugo-mod-bootstrap-scss/v5 v5.20300.20800 // indirect
 	github.com/gohugoio/hugo-mod-jslibs-dist/popperjs/v2 v2.21100.20000 // indirect

site/go.sum

@@ -6,8 +6,12 @@ github.com/SpineEventEngine/documentation/docs v0.0.0-20260930201256-1d7c3e1021b
 github.com/SpineEventEngine/documentation/docs v0.0.0-20260930201256-1d7c3e1021be/go.mod h1:fEPcJFgW19NDIdb/zGEXVPcUNVMGEBkqfgAZI0VMbVk=
 github.com/SpineEventEngine/documentation/docs v0.0.0-20261002133928-aeca7bbbea14 h1:DbEI4KZEG35Ds4GQ7N/XcniiNuA8mIz3D1muR/ZyDGM=
 github.com/SpineEventEngine/documentation/docs v0.0.0-20261002133928-aeca7bbbea14/go.mod h1:I7viy1Kfs2oYhwT7qLKL5Bem0i7ktLAOKSZGN/2Y7P8=
+github.com/SpineEventEngine/documentation/docs v0.0.0-20261030164337-3045fa4e0dd6 h1:MtFRzn0iBPUGkMczIR4ofRGF36EVU+TeCJeqWOAg+iM=
+github.com/SpineEventEngine/documentation/docs v0.0.0-20261030164337-3045fa4e0dd6/go.mod h1:I7viy1Kfs2oYhwT7qLKL5Bem0i7ktLAOKSZGN/2Y7P8=
 github.com/SpineEventEngine/site-commons v0.0.0-20261001182820-d2b63aedd0f4 h1:PoGISjoFRXwKpWwG/oTaGuSG6qF3I3THV2p+/r7qgk0=
 github.com/SpineEventEngine/site-commons v0.0.0-20261001182820-d2b63aedd0f4/go.mod h1:tkAl4StIREKmz9r5PiJtuDhvwMMkFXKWcaTyxhIikho=
+github.com/SpineEventEngine/site-commons v0.0.0-20261030153256-b79100d8a139 h1:DOYFVaEw9v3dML+40FysPUaTczyqK5+LqWJZQkK4Hs0=
+github.com/SpineEventEngine/site-commons v0.0.0-20261030153256-b79100d8a139/go.mod h1:TfFFABXgPop1uc4eBdfWZF0Es06TGmNHfReiOzkZqrk=
 github.com/SpineEventEngine/validation/docs v0.0.0-20260205202311-181ba8844107 h1:2DHRIwwLudP6l3Kh7Nd4KR4uXcsDtIAXE9adW68ivME=
 github.com/SpineEventEngine/validation/docs v0.0.0-20260205202311-181ba8844107/go.mod h1:STHyjXejVvPmfrxujfDvhofmjg55mMk+fwI3TVL0b4Y=
 github.com/SpineEventEngine/validation/docs v0.0.0-20260522175555-cf09b4c706ea h1:YEMSlr5KJXkZdK7epMSnN+6HSr2K41n8O3c8OhtF8pM=