🎉 Hinode v3: a new module generation with a redesigned argument engine

[markdumay]

Hinode v3 is here

We're excited to announce Hinode v3, a coordinated major release of the Hinode theme and its module ecosystem. At its heart is a fully redesigned argument validation engine in mod-utils v6 — the system that validates every argument you pass to shortcodes, partials, and Bookshop components.

Highlights

• Recursive argument validation. Nested arguments (like heading, illustration, or links entries) are now validated at any depth — types, permitted values, ranges, and unknown attributes. Previously only top-level arguments were checked.
• A clean new API for theme developers. The new Args.html partial returns a separated envelope (args, err, errmsg, warnmsg, defaulted) with camelCase keys. The familiar InitArgs.html keeps working as a compatibility shim, so existing shortcodes and partials don't need changes.
• Much faster builds. Argument schemas are now compiled once and cached per structure. On our own documentation site this removed roughly two minutes of cumulative template time (~84,000 validations, nearly all cache hits).
• Better diagnostics. All validation problems are reported per call (not just the first), with full paths like heading.title — and every warning tells you exactly what to fix.
• Warnings first, errors later. Newly detectable problems (wrong-typed values, unknown nested attributes, excess positional arguments) surface as warnings in this generation. They will be promoted to errors in a future major, so use the quiet period to clean up your content and templates.

The v3 module generation

Hinode v3 pins a coordinated set of module majors. If you maintain a site that imports modules directly, update the paths in your hugo.toml and go.mod:

Module	Version	Import path
hinode	v3.0.1	github.com/gethinode/hinode/v3
mod-utils	v6.4.1	github.com/gethinode/mod-utils/v6
mod-blocks	v2.0.2	github.com/gethinode/mod-blocks/v2
mod-fontawesome	v6.0.0	github.com/gethinode/mod-fontawesome/v6
mod-flexsearch	v5.0.0	github.com/gethinode/mod-flexsearch/v5
mod-leaflet	v3.0.0	github.com/gethinode/mod-leaflet/v3
mod-lottie	v3.0.1	github.com/gethinode/mod-lottie/v3
mod-mermaid	v5.0.0	github.com/gethinode/mod-mermaid/v5
mod-simple-datatables	v4.0.0	github.com/gethinode/mod-simple-datatables/v4
mod-hanko	v3.0.0	github.com/gethinode/mod-hanko/v3
mod-hubspot	v4.0.0	github.com/gethinode/mod-hubspot/v4
mod-llm	v2.0.0	github.com/gethinode/mod-llm/v2
mod-bootstrap-icons	v2.0.0	github.com/gethinode/mod-bootstrap-icons/v2
mod-flaticon	v2.0.0	github.com/gethinode/mod-flaticon/v2

Modules not listed (mod-bootstrap, mod-csp, mod-katex, and friends) are unaffected and keep their current versions.

Migrating

1. Adopt the generation together. Update Hinode and your modules to the versions above in one step. Mixing generations works technically, but a single v6-generation module flips your whole site onto the new engine — adopt deliberately, not accidentally.
2. Hugo 0.146 or later is required.
3. Watch your build log. The new engine may surface warnings about arguments your content or custom templates pass — most commonly empty strings where an argument should simply be omitted. These are non-blocking in v3 and worth cleaning up.
4. CloudCannon users: update any expose globs referencing vendored v5/v2 paths (e.g. _vendor/github.com/gethinode/mod-utils/v5/ → /v6/) and regenerate your Bookshop configuration.
5. Full details are in the mod-utils migration notes.

Quality notes

The entire generation was validated against Hinode's full block and component library — every page compared structurally against the previous production rendering, backed by a new golden-file regression suite in mod-utils covering the engine's behavior in detail. Rendered output is intended to be identical to v2; if you spot a visual difference after upgrading, please open an issue.

Happy building! 🌅

[markdumay]

📊 Follow-up: the faster builds, measured in CI

To put concrete numbers behind the "much faster builds" highlight, I compared the Lint & build matrix immediately before and after the v3 cutover (#2004). Both sides run on the identical pnpm harness — the npm→pnpm switch landed four days earlier — so the change in the Hugo build step is attributable to the new argument engine, not the CI change.

Pure Hugo build time (build:cache && build:example:ci) dropped on every platform:

Platform	v2	v3	Δ
Overall	139.7s	117.9s	−15.6%
ubuntu-latest	136.3s	117.5s	−13.8%
macos-latest	115.6s	101.0s	−12.6%
windows-latest	167.2s	135.2s	−19.1%

That's roughly −22s per build job (up to −32s on Windows), consistent across both Node 22.x and 24.x — the payoff of compiling each argument schema once and caching it per structure. It lines up nicely with the ~2 minutes of cumulative template time we saw disappear on the docs site.

Note: this is Hugo build time, not end-to-end pipeline time (which includes runner setup).

Sample: 7 v2 runs (Jul 9–12) vs 16 v3 runs (Jul 13–15), main branch, 3 OS × Node 22.x/24.x, successful runs only.

[markdumay]

For anyone upgrading a customized theme — one that overrides Hinode by shadowing its layouts, partials, or SCSS — those forked copies don't follow the module bump and can break in non-obvious ways: build errors that point at vendored files, moved partials, changed signatures.

I've expanded the upgrade guide with a section covering exactly this — re-syncing shadowed SCSS variables and the entry point, the common partial moves, and a method for exercising the override paths your own content doesn't reach:

👉 Reconciling customized templates and styles

[markdumay]

⚡ Follow-up: the build pipeline got another big boost

We further optimized the build pipeline of Hinode. The latest version v3.5.2 now sees −36.4% build time compared to v2:

Platform	v2	v3.5.2+	Δ
Overall	139.7s	88.9s	−36.4%
ubuntu-latest	136.3s	87.5s	−35.8%
macos-latest	115.6s	81.8s	−29.3%
windows-latest	167.2s	97.5s	−41.7%

Sample: 42 v2 build jobs (Jul 9–13) vs 12 v3.5.2+ jobs (Jul 17, n growing); consistent across Node 22.x and 24.x.

As a bonus, builds are now fully reproducible — building the same site twice produces byte-identical output.

[markdumay]

Update: the v3 generation, measured

Since this announcement, the v3 series has delivered three coordinated modernization rounds —
render pipeline (v3.5), styles pipeline (v3.6), and script pipeline (v3.7). Rather than
describing them feature by feature, here is the before-and-after impact, captured on Hinode's
own example site (the demo at demo.gethinode.com, ~150 pages in three languages):

Build performance (v3.2.7 → v3.5.2)

Metric (full production build)	Change
Wall time	−57%
CPU time	−43%

The render-once round eliminated duplicate content rendering and moved expensive work out of
the per-page path. Identical HTML output, verified byte-for-byte.

Stylesheets (v3.6)

CSS purging is now enabled by default (production builds only; development serves unpurged CSS,
which structurally removed a dev-server cache-poisoning failure mode):

main.css	Before	After	Change
Raw	575,913 B	257,673 B	−55%
Gzip	88,803 B	46,612 B	−47%

Scripts (v3.7)

Hinode's own JavaScript is now bundled as ES modules with Hugo's js.Build (esbuild): es2022
target, real import graph, identifier mangling, per-language parameters instead of templated
JS, and source maps in development. Custom scripts and module scripts are untouched — existing
sites need no changes.

Bundle (EN, production)	Before	After	Change
core.bundle (raw)	200,330 B	148,944 B	−25.7%
core.bundle (gzip)	54,245 B	47,927 B	−11.6%
critical.bundle (raw)	5,894 B	4,553 B	−22.7%
lottie module (raw)	251,001 B	171,431 B	−31.7%

Our production site (gethinode.com) mirrors these numbers: −54% CSS and −25% total homepage
JavaScript after adopting v3.7.

Beyond the byte counts, v3.7 also makes the leaflet, KaTeX, Lottie, and Mermaid shortcodes
self-registering (no more front-matter modules = [...] for those), turns silent
configuration mistakes into build errors, and keeps everything working on Hugo 0.146+.

Benchmarks were taken on an Apple M1 Pro against the example site; your numbers will vary
with content, but the relative gains should carry over. As always: if you spot a difference
after upgrading, please open an issue. 🌅

[markdumay]

♿ Follow-up: an accessibility & performance round

After the render (v3.5), styles (v3.6), and script (v3.7) pipelines, the v3 series added a coordinated accessibility & performance round — from v3.8 onward, together with mod-cookieyes, mod-blocks, and mod-docs — driven by a Lighthouse audit of the theme and its entire component library.

Performance

• font-display: swap for the bundled web fonts. Text now paints immediately in a fallback rather than blocking on the web font, which was sitting right on the largest-contentful-paint path.
• Back/forward cache restored. The default response headers no longer send no-store, so the browser's bfcache works again and content-hashed assets can be cached long-term (per Netlify's guidance).
• Preconnect for critical third-party modules. A module can now declare a preconnect host and the theme emits the hint in <head>, so the DNS + TLS handshake overlaps earlier work (e.g. the CookieYes CDN) — without touching load order.

Accessibility — swept across the full component library

Every element the docs render (21 blocks + 42 components) was audited. 55 of 65 pages already scored 100; the rest are now there too. Representative fixes:

• Responsive nav/tab dropdown now uses real <button> semantics (crawlable + valid ARIA), and tablist button groups expose role="tab"
• Callout/alert headings, the responsive nav toggle, and code-block line numbers now meet WCAG contrast
• Social/share buttons meet the 24×24 minimum target size
• Accessible names where they were missing — image-only cards, icon-only buttons, video-embed <iframe> titles — while the navbar brand keeps its visible text as its name (no more label-in-name mismatch)

Measured on a real Hinode site (gethinode.com, mobile Lighthouse):

Page	Performance	Accessibility	SEO
Home	81 → 96	88 → 100	100
Docs	87 → 89	88 → 100	92 → 100
Tutorial	81 → 85	93 → 100	100

On the homepage, largest-contentful-paint dropped 4.1 s → 2.5 s and Speed Index 4.9 s → 1.9 s.

The accessibility and font-loading gains apply to every Hinode site. The headline performance number still depends on deployment choices — a synchronous cookie-consent script, for instance — so it varies from site to site; the theme now gives you the preconnect and caching hooks to soften that where you can.