# Upgrade to Docsy 0.12.0 from 0.11.0

Since we didn't publish a release announcement for 0.12.0, I'm using this
opportunity to walk through the upgrade process from [0.11.0] to [0.12.0].

> **TL;DR:** The main breaking changes in Docsy [0.12.0] stem from Hugo's [new
> template system][NTS], which causes `layouts` subfolder and filename changes.

In this post you'll walk through the upgrade process for:

- **[Docsy](#update-docsy)**: [0.11.0] → [0.12.0]
- **[Hugo](#update-hugo)**: 0.136.2 → 0.147.5 [^vers-note]
- **[Node](#update-nodejs)**: LTS 20 → LTS 22 [^vers-note]

[0.11.0]: /project/about/changelog/#v0.11.0
[0.12.0]: /project/about/changelog/#v0.12.0

[^vers-note]:
    These are the officially supported Node.js and Hugo versions associated with
    the named Docsy versions. Later versions may work, but are not officially
    supported.

> [!NOTE]
>
> This post covers the common upgrade steps you're likely to encounter. Your
> project may include customizations that require additional adjustments. We
> recommend making these changes in a **separate branch** and **testing
> thoroughly** before deploying to production.

## Procedure overview

1. [Update Docsy and Hugo versions](#update-docsy-hugo-and-more)
2. [Move custom layout files and folders](#move-custom-layout-files-and-folders)
3. [Check for additional required changes](#check-for-additional-required-changes)
4. [Test your site](#test-your-site)

## Update Docsy, Hugo, and more

### 1. Update Node.js {#update-nodejs}

Docsy officially supports the active LTS release of Node.js. As of 0.12.0, this
is Node.js 22. To update your Node.js version, we recommend using [nvm]:

```sh
nvm install --lts
```

This command will both install and select the latest LTS version for your shell
session (Linux and macOS).

[nvm]: https://github.com/nvm-sh/nvm

### 2. Update Docsy {#update-docsy}

- If using NPM:

  ```bash
  npm install --save-dev google/docsy#semver:0.12.0
  ```

- If using Hugo modules:

  ```bash
  hugo mod get -u github.com/google/docsy@v0.12.0
  ```

- If using Git submodule:

  ```bash
  cd themes/docsy
  git fetch --tags
  git checkout v0.12.0
  cd ../..
  git add themes/docsy
  ```

### 3. Update Hugo {#update-hugo}

Update Hugo to 0.147.5, even if you are targeting a higher version of Hugo. We
recommend that you update to a higher version in a separate step, after the
Docsy upgrade.

How you do this depends on how your project manages its Hugo dependency. For
projects using [hugo-extended], update the NPM package version. Update the NPM
lockfile or any cache keys to force a CI/CD cache refresh. For example:

```bash
npm install --save-exact -D hugo-extended@0.147.5
```

[hugo-extended]: https://www.npmjs.com/package/hugo-extended

### 4. Install dependencies {#install-dependencies}

If using Git submodule, install Docsy dependencies:

```bash
npm install
(cd themes/docsy && npm install)
```

## Move custom layout files and folders

In line with Hugo's [new template system][NTS], Docsy v0.12.0 reorganized its
`layouts` directory[^2]. While not mandatory, we recommend updating your
project's layout files and folders to match Docsy's new Hugo-conformant layout
structure as follows:

[^2]: For implementation details, see issue [#2243].

- Move `_markup` one level up:

  ```text
  layouts/_default/_markup/  → layouts/_markup/
  ```

- Add underscore prefixes to subfolders:

  ```text
  layouts/partials/     → layouts/_partials/
  layouts/shortcodes/   → layouts/_shortcodes/
  ```

- Relocate and rename [taxonomy files](#taxonomy-files) (if applicable):

  ```text
  layouts/_default/taxonomy.html → layouts/term.html
  layouts/_default/terms.html    → layouts/taxonomy.html
  ```

The following commands can help you move your custom layout files and folders
<a id="move-layout-files"></a>:

1. Move your custom layout files and folders:

   ```bash
   # If you have custom partials
   git mv layouts/partials/* layouts/_partials/

   # If you have custom shortcodes
   git mv layouts/shortcodes/* layouts/_shortcodes/

   # If you have custom markup render hooks
   git mv layouts/_default/_markup/* layouts/_markup/

   # If you have custom taxonomy layouts
   git mv layouts/_default/taxonomy.html layouts/term.html
   git mv layouts/_default/terms.html layouts/taxonomy.html

   # Clean up empty directories
   rmdir layouts/partials layouts/shortcodes layouts/_default/_markup layouts/_default
   ```

2. Update Docsy template references:

   If you have `layouts/_markup/render-heading.html` that references Docsy's
   heading template:

   ```diff
   - {{ template "_default/_markup/td-render-heading.html" . -}}
   + {{ partial "td/render-heading.html" . -}}
   ```

   Note: The `td` prefix moved from filename to the directory path.

## Check for additional required changes

### 1. Image fingerprints {#image-fingerprints}

Skip this step if your project's CSS/SCSS does **not** use `blocks/cover`
[hero/background images][images].

Hugo generates new image [fingerprints]. Projects that refer to [hero/background
image paths][images] in their CSS/SCSS will need to update references to the new
image fingerprints. This includes projects with strict Content Security Policy
(CSP) configurations, for example.

1. Build your site: `npm run build`
2. Check `public` or `resources/_gen/images/` for image file names with new
   fingerprints
3. Update references in your stylesheets

[fingerprints]: https://gohugo.io/functions/resources/fingerprint/
[images]: /docs/content/iconsimages/#landing-pages

### 2. Taxonomy files {#taxonomy-files}

If your project overrides taxonomy layouts, note that in addition to moving the
files, you need to:

- **Swap** the layout files
- **Rename** the `terms` file to be **singular**: `terms.html` → `term.html`

For CLI commands, see the [Move layout files](#move-layout-files) step.

### 3. Internal layout `content.html` file rename {#content-html-rename}

If your project overrides Docsy `layouts/**/content.html` files:

- Prefix your file names with `_td-`: `content.html` → `_td-content.html`

These are the affected files:

```text
layouts/_td-content-after-header.html
layouts/_td-content.html
layouts/blog/_td-content.html
```

## Test your site

Build your site to check for errors, especially template-not-found errors and
missing layout files:

```bash
npm run build
```

We recommend doing this for both development **and** production builds.

Then serve your site to verify that it renders as expected. For example:

```bash
npm run serve
```

### Testing checklist

Use this checklist to verify that your upgrade succeeded:

- [ ] Build succeeds without errors, warnings, or deprecation notices; CSS and
      other asset files are rendered
- [ ] Key pages (e.g. home, a doc page, a blog post) load with no 404s or broken
      layout
- [ ] Nav links resolve; breadcrumbs show current path; current section is
      highlighted
- [ ] On mobile or tablet: navigation is usable and key pages have no horizontal
      scroll
- [ ] External links show expected styling (e.g. icon)
- [ ] [Heading self-links] work and are styled correctly
- [ ] Dark mode toggle works (if enabled)
- [ ] Custom shortcodes render correctly (if used)
- [ ] Search returns expected results (if used)
- [ ] Print preview looks correct (if used)

[Heading self-links]: /docs/content/navigation/#heading-self-links

## References

For the full release notes, see:

- [Docsy v0.12.0 changelog](/project/about/changelog/#v0.12.0)
- [Hugo release notes](https://github.com/gohugoio/hugo/releases) from 0.136.2
  (or your starting Hugo version) to 0.147.5.

Other references:

- [Hugo 0.146.0 template system][NTS]
- [0.11.0 release highlights](../2024/year-in-review/#release-highlights)
- [0.11.0 changelog](/project/about/changelog/#v0.11.0)
- [Docsy issue #2243][#2243], _Adapt to new template system in Hugo v0.146.0_.
- [0.13.0 release report and upgrade guide](/blog/2025/0.13.0/) — for upgrading
  from 0.12.0 to 0.13.0

[#2243]: https://github.com/google/docsy/issues/2243
[NTS]: https://gohugo.io/templates/new-templatesystem-overview/