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, which causes layouts subfolder and filename changes.

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

• Docsy: 0.11.0 → 0.12.0
• Hugo: 0.136.2 → 0.147.5 ¹
• Node: LTS 20 → LTS 22 ¹

Procedure overview

1. Update Docsy and Hugo versions
2. Move custom layout files and folders
3. Check for additional required changes
4. Test your site

Update Docsy, Hugo, and more

1. Update Node.js

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:

nvm install --lts

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

2. 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/[email protected]

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

npm install --save-exact -D [email protected]

4. Install dependencies

If using Git submodule, install Docsy dependencies:

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

Move custom layout files and folders

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

• 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 (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 :

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

Skip this step if your project’s CSS/SCSS does not use blocks/cover hero/background images.

Hugo generates new image fingerprints. Projects that refer to hero/background image paths 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

2. 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 step.

3. Internal layout content.html file 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:

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:

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:

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)

References

For the full release notes, see:

• Docsy v0.12.0 changelog
• Hugo release notes from 0.136.2 (or your starting Hugo version) to 0.147.5.

Other references:

• Hugo 0.146.0 template system
• 0.11.0 release highlights
• 0.11.0 changelog
• Docsy issue #2243, Adapt to new template system in Hugo v0.146.0.
• 0.13.0 release report and upgrade guide — for upgrading from 0.12.0 to 0.13.0