Hugo 0.152.0-0.155.x upgrade guide

This post summarizes the breaking and notable changes in Hugo 0.152.0 to 0.155.3. It is a companion post to the Docsy 0.14.0 and 0.13.0 release and upgrade guides.

Upgrade summary

This guide highlights breaking changes in Hugo 0.152.0–0.155.x and the actions you may need to take.

• Review BREAKING changes:
  • YAML yes/no tokens are strings
  • Build order changes for multidimensional sites
• Review deprecations (non-breaking, but recommended):
  • lang mount option deprecated
  • includeFiles/excludeFiles deprecated
• Optionally skim:
  • Known issues and fixes
  • Notable changes
• Jump to Upgrade to Hugo 0.155.x once you’re ready

YAML yes/no tokens are strings (0.152.0)

Release 0.152.0 (2025-10-21) upgrades to a more modern YAML library, which introduces a breaking change to the way that YAML interprets certain tokens across configuration files and page front matter.

Previously, the bare (unquoted) tokens yes, no, on, off, etc. were treated as boolean values. They are now treated as strings. For the complete list of tokens, see 0.152.0 release notes.

Actions: required and optional

• Applies if your project has YAML with unquoted yes, no, on, off, and similar tokens. Update them to true or false.

  Search for these unquoted key or value tokens:

  • yes, Yes, YES, y, Y, on, On, ON: change to true
  • no, No, NO, n, N, off, Off, OFF: change to false

  Example:

  # OLD (now broken in 0.152.0+)
  enabled: yes
  disabled: no
  
  # NEW (correct)
  enabled: true
  disabled: false
  

• Applies if your project has custom page Feedback configuration. You can now drop quotes around keys (or values) containing the tokens yes, no, etc..

  # OLD
  params:
    ui:
      feedback:
        enable: true
        'yes': Glad to hear it! ...
        'no': Sorry to hear that. ...
  
  # NEW
  params:
    ui:
      feedback:
        enable: true
        yes: Glad to hear it! ...
        no: Sorry to hear that. ...
  

Multidimensional content model (0.153.0)

Release 0.153.0 (2025-12-19) introduces, among other things, a powerful new multidimensional content model (over versions and roles in addition to the previously supported languages dimension) through the new sites.matrix configuration option.

Breaking and deprecation changes related to multidimensional sites are summarized next.

Build order for multidimensional sites

Hugo now builds sites based on sorted dimensions (by weight, then name) instead of starting with the default content language. This also affects .Site.Sites sort order.

Actions: required and optional

Applies if your project relies on a specific site build order or indexing into .Site.Sites by position, for example by accessing .Site.Sites by index. Update your logic to select the default site explicitly.

How you fix your code will depend on how you access the sites. For example, if your code contains index site.Sites 0, then replace it with site.Sites.Default. For more concrete examples, see open-telemetry/opentelemetry.io#8850.

Deprecations

lang mount deprecation

Actions (recommended)

Applies if you use lang on mounts. Switch to sites.matrix to avoid deprecation warnings.

For example:

# OLD (deprecated)
- source: content/fr
  target: content
  lang: fr

# NEW
- source: content/fr
  target: content
  sites:
    matrix:
      languages: ['fr']

For a concrete example, see open-telemetry/opentelemetry.io#9070.

includeFiles/excludeFiles deprecation

The includeFiles/excludeFiles file mount options are deprecated in favor of the files filter with negation support.

Actions (recommended)

Applies if you use includeFiles or excludeFiles in mounts. Switch to files to avoid deprecation warnings.

For example:

# OLD (deprecated)
- source: content
  target: content
  excludeFiles: ['drafts/**']

# NEW
- source: content
  target: content
  files: ['! drafts/**']

For a concrete example, see open-telemetry/opentelemetry.io#9070.

Known issues and fixes

Alias handling in 0.153.x

Notable changes

Notable changes that are non-breaking include:

0.155.0

• Version and dimension range queries are now supported in the sites matrix (e.g., >= v1.0.0).
• Page aliases now work properly in multidimensional sites.
• XMP and IPTC image metadata support was added.

0.154.0–0.154.5

• Partial decorators introduced (inner keyword) for powerful template composition.
• New Page.OutputFormats.Canonical method (0.154.4).
• New reflect.* functions, such as reflect.IsPage.
• Critical fixes for alias handling and site redirects in multidimensional/multihost setups.

0.153.0

• WebP encoding/decoding now uses libwebp via WASM. The extended edition is no longer required for WebP.
• Animated WebP support, including conversion to/from animated GIFs.
• GoogleAnalytics.RespectDoNotTrack default changed to true.
• Duplicate content path warnings were removed (less noisy, but may hide issues).
• macOS distributions are now distributed solely as signed and notarized .pkg installers, .tar.gz is no longer supported. See the notes below.

Upgrade to Hugo 0.155.x

After addressing all breaking changes and deprecations, upgrade to the latest release of Hugo 0.155.x. If you use the hugo-extended NPM package, you can upgrade to the latest version by running:

npm install hugo-extended@latest

If you use hvm to manage your Hugo version, you can upgrade to the latest version by running:

hvm use latest

Recommended minimum Hugo version

For projects using the new sites matrix features who also want the latest fixes and updated support for aliases in the context of multidimensional sites, we recommend using Hugo 0.155.3 or later:

module:
  hugoVersion:
    min: '0.155.3'

• ←Previous
• Next→