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 peer version upgrade¹: 0.136.2 → 0.147.5

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 and Hugo versions

1. Update Docsy

• If using NPM:

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

• If using Hugo modules:

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

• If using Git submodule:

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

2. Update Hugo version

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 hugo-extended@0.147.5

3. 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 it’s 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:

  layouts/_default/_markup/  → layouts/_markup/
  

• Add underscore prefixes to subfolders:

  layouts/partials/     → layouts/_partials/
  layouts/shortcodes/   → layouts/_shortcodes/
  

• Relocate and rename taxonomy files (if applicable):

  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:

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

   - {{ 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
• All pages render correctly
• CSS/SCSS compiles properly
• External link styling works
• Heading self-links work and are styled correctly
• Navigation and breadcrumbs work
• Dark mode toggle works (if enabled)
• Mobile/responsive layout works
• Custom shortcodes work
• Search functionality works
• Print layouts work (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.

• ←Previous
• Next→