alexander-yevsyukov · Oct 30, 2026 · Oct 30, 2026 · Oct 30, 2026 · Oct 30, 2026 · Oct 30, 2026
diff --git a/.agents/tasks/hugo-0-169-upgrade.md b/.agents/tasks/hugo-0-169-upgrade.md
@@ -0,0 +1,52 @@
+---
+slug: hugo-0-169-upgrade
+branch: hugo-0.169
+owner: claude
+status: in-review
+started: 2026-10-30
+---
+
+## Goal
+
+`docs/_preview` builds and runs on Hugo v0.169.0 with the latest `site-commons`,
+and CI checks links with the same Hugo version.
+
+## Context
+
+- #89 — upgrade Hugo to v0.169.0 (meta-issue; also `site-commons`, `spine.io`).
+- #92 — Hugo v0.162.0+ rejects `text/html` content files. The full-screen
+  architecture diagram is one. Fix: option A from the issue, allow HTML content
+  in the project config (`security` is ignored when set in a module config).
+- #93 — pick up `site-commons` with the bundled code-highlighting palettes
+  (SpineEventEngine/site-commons#37, merged). That theme declares
+  `module.hugoVersion.min = '0.169.0'` and uses relative partial paths
+  (Hugo v0.167.0+), 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; `config` needs
+  the same bump, or the next `./config/pull` reverts it.
+
+## Plan
+
+- [x] Allow HTML content in `docs/_preview/hugo.toml` (#92).
+- [x] `hugo mod get -u github.com/SpineEventEngine/site-commons` in
+  `docs/_preview` (#93).
+- [x] Bump `HUGO_VERSION` in `check-links.yml` to `0.169.0` (#89).
+- [x] Update Hugo and Go prerequisites in `README.md` (#89).
+- [x] Build `docs/_preview` with v0.169.0: no errors, no new warnings.
+- [x] Check the full-screen diagram page: URL, back link, JS, PDF link.
+- [x] Check the code-theme toggle in the preview (#93).
+- [x] Check that `spine.io` builds with the same `security` setting (local only).
+- [x] Run link check.
+
+## Log
+
+- 2026-10-30 — drafted and started (autonomous run requested by the user).
+- 2026-10-30 — the preview builds on v0.169.0; pages change only as
+  site-commons#37 intends. Full-screen diagram and code-theme toggle checked
+  in the browser. A clone of `spine.io` fails on v0.169.0 without
+  `allowContent` and builds with it (`--minify`, updated theme).
+- 2026-10-30 — link check: the Lychee run passes, but 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, 13 body links are
+  broken, the same on `master`: 12 in `validation/docs`, and one Stack Overflow
+  link that answers 403 to bots. None comes from this branch.
diff --git a/.github/workflows/check-links.yml b/.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

diff --git a/README.md b/README.md
@@ -19,9 +19,9 @@ are working as intended. It allows making changes more convenient for authors.
 ## Prerequisites
 
 1. JDK 8 (x86_64).
-2. [Go][go] `1.22` or newer (matches `docs/go.mod`).
+2. [Go][go] `1.27.3` or newer (matches `docs/_preview/go.mod`).
 3. [Node.js][nodejs] `18+`.
-4. [Hugo Extended][hugo-quick-start] in version `v0.150.0` or higher.
+4. [Hugo Extended][hugo-quick-start] in version `v0.169.0` or higher.
 
 ## Configuration
 

diff --git a/docs/_preview/go.mod b/docs/_preview/go.mod
@@ -1,9 +1,9 @@
 module github.com/SpineEventEngine/documentation/docs/_preview
 
-go 1.22.0
+go 1.27.3
 
 require (
-	github.com/SpineEventEngine/site-commons v0.0.0-20261001182820-d2b63aedd0f4 // 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

diff --git a/docs/_preview/go.sum b/docs/_preview/go.sum
@@ -1,5 +1,7 @@
 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=

diff --git a/docs/_preview/hugo.toml b/docs/_preview/hugo.toml
@@ -22,6 +22,14 @@ disableKinds = ['taxonomy', 'term']
   [caches.getresource]
     maxAge = '1h'
 
+# Since v0.162.0, Hugo denies HTML content files by default. The full-screen architecture
+# diagram, `spine-architecture-diagram-full-screen.html`, is such a file, so HTML is allowed.
+# Org mode stays denied. Hugo ignores the `security` settings of an imported module, so
+# `docs/hugo.toml` cannot carry this setting. Each site that imports `docs`, such as
+# spine.io, needs it too.
+[security]
+  allowContent = ['! ^text/org$']
+
 # Enables HTML rendering in markdown files.
 [markup]
   [markup.goldmark]