# Upgrading to Hinode v3

Upgrade your existing Hinode site to the v3 module generation with its redesigned argument validation engine.

Added in v3.0.0

> [!NOTE]
> Still on Hinode v1 or earlier? Check out [Upgrading to Hinode v2](upgrading-hinode-v2/) first and work your way up one major version at a time.

Hinode Added in 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](https://github.com/gethinode/template) running a v2-compatible site. Please use [GitHub discussions](https://github.com/gethinode/hinode/discussions) when encountering any challenges, or the [issue tracker](https://github.com/gethinode/hinode/issues) 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:

| 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, 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:

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

After:

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

Next, refresh the module dependencies and vendor folder:

```bash
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:

```yaml
# 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](https://cloudcannon.com) with the `setup-cloudcannon-cms` utility, update any expose globs that reference vendored module paths, for example:

```yml
# 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](https://github.com/gethinode/mod-utils#argument-validation) for the full API reference and migration notes.