Hugo 0.158.0-0.164.x upgrade guide

This post is a companion to the Docsy 0.16.0 release post, which specifies the Hugo versions that 0.16.0 requires and validates.

Upgrade summary

• This guide is for you if you’re:
  • Upgrading to Docsy 0.16.0
  • Upgrading only Hugo
• Review BREAKING changes:
  • Node 22+ is required for Hugo-managed Node tools
  • HTML content and symlink security changed
• Review deprecations:
  • Language config and template APIs
  • Imaging config and template APIs
• Optionally skim:
  • Markdown-link escaping
  • Image URL churn
  • Template and module cleanup
  • Faster builds and stricter templates
  • Notable changes
• Jump to Upgrade to Hugo 0.164.0 once you’re ready.

Language API deprecations (0.158.0)

Hugo 0.158.0 renamed several language configuration keys and template methods. The old names log deprecation notices first, then move toward warnings and eventual errors on Hugo’s deprecation timeline.

Docsy’s own templates and docs now use the new names – one of the changes behind 0.16.0’s raised Hugo minimum.

Actions

Applies if your multilingual site config uses older language keys. Rename them when convenient, then check your language menu output:

# OLD
languages:
  en:
    languageName: English
    languageDirection: ltr

# NEW
languages:
  en:
    label: English
    direction: ltr

Applies if your site overrides language-related templates or partials. Review custom template code for these replacements:

For current Docsy examples, see Multi-language support.

Markdown-link escaping (0.159.2, fixed in 0.160.0)

Hugo 0.159.2 included a security fix for dangerous URLs in Markdown links and images. It also introduced a regression that could double-escape & in rendered Markdown link URLs, producing & in HTML output.

Hugo 0.160.0 fixed that regression, and Hugo 0.160.1 is the safer 0.160.x patch release. Docsy 0.16.0’s minimum Hugo version, 0.160.1, already excludes this window.

Actions

Applies if you briefly tested or deployed Hugo 0.159.2: search generated HTML for & in link URLs.

Template and module cleanup (0.159.x-0.160.x)

Hugo 0.159.x continued several cleanup paths that may show up in older Docsy sites, Docsy forks, or large downstream sites with local template overrides.

Actions

Applies if your site has custom templates, module mounts, or conversion scripts.

• Replace deprecated site.Data usage with hugo.Data.
• Replace deprecated includeFiles and excludeFiles module mount options with files.
• Replace deprecated :filename permalink placeholders with :contentbasename.
• If you run hugo mod npm pack, test it after upgrading.
• If you use hugo convert, review generated output before committing it.

Applies if your site uses Goldmark passthrough, RenderShortcodes, or multilingual root sections. Hugo 0.160.1 fixed regressions in this range around passthrough elements in headings, shortcode rendering context markers, and multilingual root section generation; include such pages in your smoke tests.

Node-managed tools (0.161.x)

Hugo 0.161.x runs Node-based tools such as PostCSS, Babel, and Tailwind under Node’s --permission sandbox. This requires Node 22 or later.

Docsy sites commonly use PostCSS for CSS processing, so this can be a practical breaking change even when the Docsy theme itself has not changed. Hugo 0.163.2 and 0.163.3 fix regressions in this permission model, so prefer 0.163.3 or later for PostCSS pipelines.

Actions

Applies if your site uses Hugo 0.161.x or later and runs PostCSS, Babel, Tailwind, or similar Node tools during the Hugo build.

• Upgrade Node to the active LTS release. For Docsy 0.16.0, use Node LTS 24.
• Build locally and check for Node permission errors.
• If your CI keeps node_modules outside the project tree (for example, Netlify’s shared cache) and the build fails with ERR_ACCESS_DENIED, upgrade to Hugo 0.163.2 or later.
• If your PostCSS or Babel config uses an .mjs or .cjs variant (for example, postcss.config.mjs), use Hugo 0.163.3, which resolves those variants.
• If your project uses Tailwind, install Tailwind as an npm package. Hugo no longer supports the standalone Tailwind binary in this path.
• If a Node tool legitimately spawns child processes and Hugo 0.161.1 or later blocks it, review security.node.permissions.AllowChildProcess.

Content and resource security (0.161.x-0.163.x)

Hugo tightened several security boundaries in this range:

• security.http.urls defaults became more restrictive, and resources.GetRemote re-checks redirects.
• text/html content files are denied by default unless allowed through security.allowContent.
• Symlinked entries are rejected or ignored by more template/resource functions, including resources.Get and, in 0.163.1, os.ReadDir, os.ReadFile, os.Stat, and os.FileExists.

Actions

Applies if your site uses remote resources, hand-authored .html content files, symlinked content/assets, or templates.Defer inside cached partials.

• Build locally with your target Hugo version and review security-related errors or warnings.
• If you intentionally publish .html content files, configure security.allowContent explicitly.
• If templates call resources.GetRemote, review security.http.urls and test redirecting URLs.
• If your content or assets are symlinked into the project, test those pages and consider replacing symlinks with Hugo mounts or real files if Hugo blocks them.
• If templates use templates.Defer inside partialCached, move that deferred work outside the cached partial; Hugo now reports this invalid combination instead of silently doing the wrong thing.

Imaging deprecations and URL churn (0.163.x)

Hugo 0.163.0 deprecated global imaging quality settings in favor of per-format settings. It also introduced AVIF-related imaging configuration and changed internal resized-image cache keys.

Actions

Applies if your site config uses global imaging.quality or imaging.compression.

• Replace global settings with per-format settings, or remove them if they match Hugo defaults.

• Keep resampleFilter: CatmullRom if your site relies on Docsy-style sharp photographic downscaling:

  imaging:
    resampleFilter: CatmullRom
  

Image URL churn

Applies if your site commits generated output, compares public builds, or uses a CDN that caches generated image resources aggressively.

Hugo 0.161.x-0.163.x can change resized-image filenames that contain _hu_<HASH> even when the source image and visual output are unchanged. Treat this as expected cache-key churn. It can create noisy diffs and cache misses, but it is not usually a content regression: when diffs appear, verify the rendered images, not just the filenames.

Faster builds and stricter templates (0.164.0)

Hugo 0.164.0 fixes a template-rendering slowdown that affected Hugo 0.128.0 through 0.163.x. Large sites benefit the most: on a reported ~8,500-page Docsy site, the fix cut full-build time from 608 to 117 seconds (performance discussion).

The same release tightens template handling and refreshes syntax highlighting:

• resources.PostProcess is deprecated; use templates.Defer instead. Docsy’s templates don’t use resources.PostProcess.
• .Render now fails the build when the named view template is missing, instead of silently rendering nothing; nested view names work again.
• The bundled Chroma highlighter retokenizes some languages, such as protobuf, YAML, and Markdown: syntax-highlighting classes change, text content does not.
• In multilingual sitemaps, each URL’s xhtml:link alternates now list the entry’s own language first.

Actions

Applies if your site is large, overrides or adds templates, or commits generated output.

• Benchmark a clean production build; template-heavy sites may see large build-time wins.
• Replace resources.PostProcess with templates.Defer in custom templates.
• Fix any .Render calls that name a missing view template; they now fail the build.
• Treat syntax-highlighting class changes and sitemap alternate-link reordering as expected output churn.

Other deprecations and notable changes

Template and config deprecations

Review these if your site has custom templates, external content converters, or JavaScript tooling config:

• .IsNode is deprecated; use .IsBranch.
• jsconfig baseUrl support was removed.
• If you read Git metadata from module-mounted pages, verify .Page.GitInfo output. Hugo 0.162.0 fixed GitInfo handling for modules whose go.mod lives in a repository subdirectory.
• If you use --renderSegments, prefer Hugo 0.163.1 for its segment-merge fix.
• If your site sets uglyURLs: true and has a page and a section sharing a name (for example, download.htm beside download/), use Hugo 0.163.3, which fixes a rendering collision introduced earlier in the 0.163.x range.
• If your site renders Pandoc or reStructuredText content through external converters, Hugo 0.163.2 now fails the build when the converter binary is missing (matching AsciiDoc) instead of silently publishing raw content; ensure the converter is installed wherever you build.

Security fixes

This range includes multiple security-related updates, including Go html/template fixes and stricter URL/content handling. Hugo 0.163.3 also hardens the default code-block render hook: the language token (info string) of fenced code blocks is now escaped, which matters most for sites that render untrusted Markdown. This is a strong reason to prefer 0.163.3 or later over stopping at 0.160.1.

New features worth knowing about

• css.Build and later hugo:vars support may be useful for site-specific CSS pipelines, but Docsy has not moved its Sass/PostCSS pipeline to css.Build.
• AVIF image processing was added and then tuned in the 0.162.x-0.163.x range.
• strings.ReplacePairs is available for template authors on Hugo 0.158.0 or later.
• On Hugo 0.164.0, hugo gen chromastyles gains --mode and --modeSelector flags for generating combined light/dark syntax-highlighting stylesheets.

Upgrade to Hugo 0.164.0

After addressing applicable breaking changes and deprecations, upgrade to Hugo 0.164.0.

If you use the hugo-extended npm package:

npm install --save-exact --save-dev hugo-extended@0.164.0

If you use hvm:

hvm use 0.164.0/extended

For other installation methods, see Install Hugo.

Sanity checks

Confirm that you’ve addressed every action that applies to your site. Then:

• Upgrading as part of Docsy 0.16.0? Continue with its upgrade section.
• Otherwise, finish with the generic site checks.

• ←Précédent
• Suivant→