[alexander-yevsyukov]

This PR moves the documentation preview to Hugo v0.169.0 and the latest site-commons theme.

Fixes #92.
Fixes #93.
Part of #89.

Changes

Allow HTML content files (#92)

docs/_preview/hugo.toml now has:

[security]
  allowContent = ['! ^text/org$']

This is option A from #92. Since Hugo v0.162.0, text/html content files are denied by default. The full-screen architecture diagram is one, so the build failed on newer Hugo versions.

• The page stays an HTML file, with its URL unchanged.
• Org mode stays denied, as in Hugo's default.
• It doesn't widen what content can do. Goldmark's unsafe renderer is already on, so Markdown pages can already contain raw HTML.
• The setting can't go into docs/hugo.toml. Hugo ignores security in the config of an imported module, so each site that imports docs needs it. The comment in hugo.toml says so.

Update site-commons (#93)

hugo mod get -u github.com/SpineEventEngine/site-commons picked up SpineEventEngine/site-commons#36 and SpineEventEngine/site-commons#37.

• The theme now bundles the code-highlighting palettes into main.css.
• It requires Hugo v0.169.0 (module.hugoVersion.min) and Go 1.27.3. Go raised the go directive in docs/_preview/go.mod to 1.27.3 to match.

Hugo v0.169.0 (#89)

• HUGO_VERSION in check-links.yml is now 0.169.0. The theme's relative partial paths need at least v0.167.0, so link checks can't run on v0.161.1 anymore.
• README.md now lists Hugo v0.169.0 and Go 1.27.3 as prerequisites.

I went through the release notes from v0.162.0 to v0.169.0. The two shortcodes in this repo don't need changes or benefit from the new features. The theme adopted them in SpineEventEngine/site-commons#36.

Verification

All builds used Hugo v0.169.0 extended and Go 1.27.3.

Check	Result
docs/_preview on master	Fails with access denied: "text/html" is not whitelisted in policy "security.allowContent"
docs/_preview with allowContent	Builds, 95 pages
docs/_preview with the new theme	Builds, 95 pages
allowContent semantics, on a scratch site	.html accepted, .org still denied

Output with the old and the new theme. I compared the two builds with the asset fingerprints normalised and whitespace ignored.

• All 77 changed pages have the same change: the inline theme script from Bundle the code-highlighting palettes into the SCSS (option B of #35) site-commons#37 and no separate code-theme/*.css link.
• The only other difference is the random IDs from cloakemail on one page, which change on every build.
• code-theme/light.css and code-theme/dark.css are gone; the hl-text-only rules are now in main.css.

In the browser, with hugo server:

• View full screen on the Architecture page opens the same URL as before.
  • The page loads architecture-diagram.js and the inline SVG, with no console errors.
  • The diagram is interactive: the "all server-side components" toggle works and hovering a caption highlights it.
  • The close button links back to the Architecture page. The Download PDF link opens the PDF, which is served with status 200.
• Code theme, on the Naming Conventions page:
  • Toggling switches the colors at once, with no stylesheet to load.
  • The hl-text-only line keeps its emphasis.
  • Reloading in the light theme renders light from the start, because the inline <head> script sets data-theme before main.css loads.

spine.io, on a fresh clone with the new theme and this repo's docs as the module:

• Without allowContent, the build fails with the same error.
• With allowContent = ['! ^text/org$'] in site/config/_default/hugo.toml, hugo --minify builds. The full-screen page, its script and the PDF are published.

Link check. Lychee 0.24.2 with lychee.toml against hugo -e development passes, but that result says little.

• Lychee extracts only the <head> URLs from our pages. Every page has an inline jQuery block in <head>, and after it Lychee finds no links in the body.
  • On the Architecture page it finds 7 URLs with the block and 86 without it.
  • CI has the same blind spot. The last run on master reported 8 Unique ✅ 616 OK for 77 pages.
• With that block stripped from copies of the output, 13 body links are broken. The same 13 are broken on master, so none comes from this PR.
  • 12 are in the validation/docs module, e.g. ../06-developers-guide/ and links to moved .agents/* files.
  • 1 is a Stack Overflow /a/ link in guides/validation.md. It redirects to a /questions/ page, which answers 403 to bots.

Follow-ups

• spine.io needs the same allowContent setting, the theme update, and HUGO_VERSION: 0.169.0 in gh-pages.yml and check-links.yml. This is the spine.io part of Upgrade Hugo to v0.169.0 #89.
• config distributes check-links.yml and still pins HUGO_VERSION: 0.161.1. The next ./config/pull would bring that back here, so config needs the same bump.
• Link checking. The blind spot above means CI checks no body links. Fixing it, in site-commons or in the config workflow, will turn up the 13 broken links, so they need fixing then too.
• LibSass. Every build prints WARN deprecated: css.Sass: libsass was deprecated in Hugo v0.153.0. The call is in the theme's stylesheet.html, and the warning shows on master too. Moving to Dart Sass is tracked in Move from LibSass to Dart Sass site-commons#38.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-30T16:19:01.278901Z	bb9375d	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[Copilot]

🟢 Approved

No active review issues require resolution for the documentation preview upgrade.

No open issues 🎉

What changed in this PR

Updates the documentation preview to Hugo v0.169.0 and the latest site-commons, enabling HTML content files and adopting bundled code-highlighting palettes.

Changes:

• Allows the full-screen architecture diagram’s HTML content while keeping Org-mode content denied.
• Updates the theme dependency and documents Go 1.27.3 and Hugo Extended v0.169.0 prerequisites.
• Aligns the link-check workflow’s Hugo version and records verification results and follow-ups.

File	Description
README.md	Updates Go and Hugo prerequisites.
docs/​_preview/​hugo.toml	Allows HTML content and explains the per-site configuration requirement.
docs/​_preview/​go.sum	Adds checksums for the updated theme.
docs/​_preview/​go.mod	Updates site-commons and raises the Go directive to 1.27.3.
.github/​workflows/​check-links.yml	Updates the Hugo pin to 0.169.0.
.agents/​tasks/​hugo-0-169-upgrade.md	Records the upgrade plan, verification results, and remaining follow-ups.

_{Review effort: Balanced}