Upgrading to Hinode V3

  Note

Still on Hinode v1 or earlier? Check out Upgrading to Hinode V2 first and work your way up one major version at a time.

Hinode v3.0.0  is a coordinated release of the theme and its companion modules, known as the v3 module generation. At its heart is a redesigned argument validation engine in mod-utils v6: arguments passed to shortcodes, partials, and content blocks are now validated recursively at any nesting depth, with clearer diagnostics and substantially faster builds. The engine keeps full compatibility with existing call sites, so most sites upgrade by updating module versions alone. This guide targets users of the Hinode template  running a v2-compatible site. Please use GitHub discussions  when encountering any challenges, or the issue tracker  for bug reports.

Meeting the prerequisites  

The prerequisites are unchanged from v2: Hugo Extended 0.146.0 or later, and the Dart Sass transpiler. If your site pins an older hugo-bin or hugo-extended package, bump it to a release that provides Hugo 0.146+.

Updating the module imports  

Hinode v3 uses a new Go module path (hinode/v3) and pins a coordinated set of module majors. Update the import paths in config/_default/hugo.toml for every module your site uses:

Modules not listed, such as mod-bootstrap, mod-csp, and mod-katex, are unaffected and keep their current versions.

As an example, update the Hinode import as follows:

Before:

[[module.imports]]
  path = "github.com/gethinode/hinode/v2"

After:

[[module.imports]]
  path = "github.com/gethinode/hinode/v3"

Next, refresh the module dependencies and vendor folder:

hugo mod get github.com/gethinode/hinode/v3@v3.0.1
npm run mod:tidy
npm run mod:vendor

  Important

Adopt the generation together: update Hinode and all listed modules in a single step. Adding a single v3-generation module to a v2 site switches the entire site to the new validation engine through Hugo’s module mounts — technically compatible, but easy to do by accident and confusing to debug.

Reviewing the build output  

The new engine validates arguments recursively and reports every problem it finds, not just the first. Newly detectable problems — wrong-typed values, unknown nested attributes, and excess positional arguments — surface as warnings in this generation. They will be promoted to errors in a future major release, so use the quiet period to clean up your content and custom templates.

The most common warning after upgrading is an empty string passed where an argument should simply be omitted:

# triggers a warning: empty string is not a valid select value
navigation:
  color: ""

Remove the key instead of assigning an empty value.

Two behavioral refinements are worth knowing when reviewing custom templates:

• Argument defaults defined in the schema are now applied consistently, including false and 0 values that previous releases silently skipped.
• When a component declares both a current argument and a deprecated alias (such as show-preview and show_preview), the current argument always takes precedence and deprecated aliases no longer receive defaults.

Rendered output is intended to be identical to v2. The generation was validated against Hinode’s full block and component library; if you spot a visual difference after upgrading, please open an issue.

Updating CloudCannon configurations  

If your site uses CloudCannon  with the setup-cloudcannon-cms utility, update any expose globs that reference vendored module paths, for example:

# before
- _vendor/github.com/gethinode/mod-utils/v5/layouts/**/*.html
# after
- _vendor/github.com/gethinode/mod-utils/v6/layouts/**/*.html

Regenerate the Bookshop configuration afterwards (npm run config) and verify visual editing on your connected site.

Adopting the new argument API (optional)  

Sites and themes with custom shortcodes or partials can keep using InitArgs.html — it remains fully supported as a compatibility shim. When you are ready, migrate to the new Args.html partial for a cleaner contract: a separated result envelope (args, err, errmsg, warnmsg, defaulted), camelCase argument keys, and strict validation. See the mod-utils documentation  for the full API reference and migration notes.