Hugo 0.158.0-0.163.x upgrade guide

This post summarizes breaking, security, and notable changes in Hugo 0.158.0 to 0.163.2 that are relevant to Docsy users. It is a companion post to the Docsy 0.16.0 release and upgrade guide.

Docsy 0.16.0 requires Hugo 0.158.0 or later. The Docsy project build is tested with Hugo 0.163.2, which is the recommended target for this upgrade range.

Upgrade summary

This guide highlights Hugo changes that may require action when upgrading a Docsy site to 0.16.0.

• Review BREAKING changes:
  • Docsy now requires Hugo 0.158.0 or later
  • 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
  • Notable changes
• Jump to Upgrade to Hugo 0.163.2 once you’re ready.

Hugo version for Docsy 0.16.0

Docsy 0.16.0 raises the theme’s minimum supported Hugo version from 0.146.0 to 0.158.0. Theme templates now use Hugo language APIs introduced in 0.158.0, so older Hugo versions will fail with template errors.

The theme minimum remains 0.158.0 through the 0.163.x range. However, we recommend upgrading directly to Hugo 0.163.2 because the later releases include security fixes, avoid a short-lived 0.159.x link-escaping regression, and are the versions validated across Docsy, the Docsy example site, and at least one large downstream Docsy site.

Actions

Applies to all sites upgrading to Docsy 0.16.0.

• Upgrade Hugo to 0.158.0 or later. Prefer 0.163.2.

• If your project declares module.hugoVersion.min, set it to at least 0.158.0.

• If you use hugo-extended, pin a compatible version in your site:

  npm install hugo-extended@0.163.2 --save-dev
  

• If you use hvm, select the latest compatible Hugo release:

  hvm use 0.163.2
  

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, which is why Docsy 0.16.0 requires Hugo 0.158.0 or later.

Actions

Applies if your multilingual site config uses older language keys. Rename them when convenient:

# 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 to 0.160.1)

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. If you are moving through this range, do not stop at 0.159.2.

Actions

Applies if you briefly tested or deployed Hugo 0.159.2.

• Upgrade to Hugo 0.160.1 or later.
• Search generated HTML for & in link URLs.
• Pay closest attention to monolingual sites without custom link render hooks.

Multilingual single-host sites are usually shielded because Hugo’s useEmbedded: auto behavior activates the embedded link render hook. Sites with custom link render hooks are also usually shielded. The safest path is still to use Hugo 0.160.1 or later.

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. Hugo 0.160.1 then fixed several rendering issues in this range.

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. Prefer Hugo 0.160.1 or later and include these pages in smoke tests. Hugo 0.160.1 fixed relevant regressions around passthrough elements in headings, shortcode rendering context markers, and multilingual root section generation.

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 continues to recommend Node LTS 24 for supported builds.

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 fixes an ERR_ACCESS_DENIED regression in this permission model that could abort builds when node_modules lives outside the project tree, such as in a CI provider’s shared cache (for example, Netlify). It is another reason to prefer 0.163.2 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.
• If your project uses Tailwind, install Tailwind as an npm package. Hugo no longer supports the standalone Tailwind binary in this path.

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.

Docsy’s own workspace and smoke-test install shapes were validated across these changes, but site-specific mounts, symlinks, and remote resource fetches are always project-specific.

Actions

Applies if your site uses remote resources, hand-authored .html content files, or symlinked content/assets.

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

Docsy’s website configuration was streamlined as part of the upgrade: settings that matched Hugo defaults were removed, and resampleFilter: CatmullRom was kept because it materially affects photo downscaling quality.

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.

For example:

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.

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 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. This is a strong reason to prefer 0.163.2 over stopping at the minimum 0.158.0.

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.

Upgrade to Hugo 0.163.2

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

If you use the hugo-extended npm package:

npm install hugo-extended@0.163.2 --save-dev

If you use hvm:

hvm use 0.163.2

Recommended minimum Hugo version

Docsy 0.16.0 requires Hugo 0.158.0 or later:

module:
  hugoVersion:
    min: 0.158.0

For local builds, deployments, and new upgrades, we recommend Hugo 0.163.2.

• ←Previous
• Next→