How the Hugo System Works (as of 2026-07-29)

This note documents the Hugo architecture of PKB-theme as it stands today, after the alignment with Hugo v0.164.0. It is a dated snapshot: Hugo moves quickly, so check the version floor and the SOTA survey before relying on details here.

Version floor and why

The theme requires Hugo v0.164.0 (theme.toml min_version, CI pin, README). The floor is set by four features the theme now depends on: useEmbedded render-hook enums (v0.148.0), the locale config key replacing languageCode (v0.158.0), per-format imaging config plus [imaging.meta] (v0.163.0), and Chroma dark/light style pairs (v0.164.0). The v0.146 template-system rewrite shapes the entire layouts/ tree.

SOTA: Hugo Static Site Generator

As of 2026-07-28. Mode: survey (repo-grounded against PKB-theme). Freshness: findings older than 12 months are flagged [STALE]. Every numbered claim ends with its source and access date; anything unverifiable is marked [UNVERIFIED].

TL;DR

• The latest Hugo release is v0.164.0 (2026-07-06). Roughly 25 minor releases shipped in the last 19 months; the project is very actively maintained, still centered on Bjørn Erik Pedersen.
• The big theme-author events of the period: the v0.146 template-system rewrite (new layouts/ structure), v0.148 render-hook useEmbedded enums (replacing enableDefault), the v0.156 mass removal of long-deprecated APIs, v0.158 languageCode → locale, v0.163 per-format imaging config, and v0.164 resources.PostProcess → templates.Defer.
• PKB-theme’s in-progress migration to useEmbedded = 'fallback' is correct (minimum version v0.148.0, verified). But its CI pins Hugo 0.123.7 / 0.128.0 - below the theme’s own min_version = "0.136.0" and far below the README’s new “v0.148+” claim. Aligning versions is the top action.
• Concrete code updates for this repo: replace .Page.Scratch (deprecated v0.138.0) in the cite/sidenote shortcodes, move the global imaging.quality into per-format blocks, rename languageCode → locale, and audit two non-standard render hooks (render-inline.html, render-paragraph.html) that are not part of Hugo’s documented hook set.

Landscape

Release train & maintenance

Hugo ships a minor release roughly every 3–5 weeks with patch releases in between. From v0.140.0 (2024-12-17) to v0.164.0 (2026-07-06) there were 25 minor lines, the majority of which introduced at least one deprecation or small breaking change - Hugo deprecates aggressively and removes on a ~6–18 month horizon. Maintenance is healthy but concentrated: bep accounts for ~60–68% of commits; jmooring is the most visible secondary maintainer; ~210 open issues with closure rate exceeding creation rate over the last year. License: Apache-2.0. No formal public roadmap - direction is visible via GitHub milestones (v0.165.0 is the current one). (releases, contributors, milestone 370, accessed 2026-07-28)

This is a comprehensive test post designed to showcase the various features and capabilities of the PKB theme. It includes multiple markdown elements, components, and formatting options to ensure everything renders correctly.

Introduction

Welcome to our test archetype! This post demonstrates how different content types render within the theme. From basic text formatting to complex components like tables, code blocks, and mathematical expressions^aa.Sidenotes are particularly useful for additional context without breaking the reading flow.

Development Tips

Serving exampleSite

For theme development, use this command to serve the exampleSite with debug options:

hugo server \
  --source exampleSite \  # Point to exampleSite directory
  --noHTTPCache \         # Disable HTTP caching
  --renderToMemory \      # Render to memory
  --disableFastRender \   # Disable fast render
  --ignoreCache \         # Ignore cache
  --gc \                  # Run garbage collection
  --logLevel debug \      # Set debug log level
  -D                      # Include draft posts

Command Explanation

• --source exampleSite: Serves the example site instead of the main project
• --noHTTPCache: Prevents browser caching during development
• --renderToMemory: Renders pages in memory for faster development
• --disableFastRender: Forces full re-render of changed pages
• --ignoreCache: Ignores the cache when rebuilding
• --gc: Runs garbage collection after builds
• --logLevel debug: Shows detailed debug information
• -D: Includes draft content

Local Testing

For production testing, remove debug flags: