v0.153.0
gohugoio/hugov0.153.0Dec 19, 2025by bep
AI Summary
A major release introducing a multidimensional content model (sites matrix), a complete WebP overhaul using WASM (supporting animations), and improved Asciidoctor integration.
Key Highlights
- New multidimensional content model (sites matrix) with 'complements' feature.
- New WebP support via libwebp WASM (no extended edition needed, supports animations).
- New template functions: urls.PathEscape, urls.PathUnescape, openapi3.Unmarshal (external refs).
- Signed and notarized macOS pkg installers.
Breaking Changes
- lang option on mounts and segments is deprecated in favor of sites.matrix.
- File mount includeFiles and excludeFiles are deprecated in favor of new files filter.
- YAML boolean parsing changed: yes/no/on/off are now strings, not booleans.
New Features
- urls.PathEscape and urls.PathUnescape functions.
- openapi3.Unmarshal support for external file references.
- rotate() method for content tree manipulation.
- Sites complements feature for filling translation gaps.
Full Release Notes
> [!note]
>There is a newer bug fix release available [here](https://github.com/gohugoio/hugo/releases/tag/v0.153.1).
This is a good one! Hugo `v0.153.0` comes with a powerful new multidimensional content model (languages, versions and roles) and completely overhauls WebP image support, and much more:
* For the new multidimensional content model, start reading [sites matrix](https://gohugo.io/quick-reference/glossary/#sites-matrix) and [sites complements](https://gohugo.io/quick-reference/glossary/#sites-complements). The matrix is what gets written to disk, `complements` allows e.g. a site in Swedish to fill in missing gaps in the site in Norwegian's page and resource collections. Also see the new [Rotate](https://gohugo.io/methods/page/rotate/) method, that allows you to rotate the content tree in a given dimension.
* For WebP we now build a WASM version of [libwebp](https://github.com/webmproject/libwebp/) (`v1.6.0`) and run it in the [Wazero](https://wazero.io/) runtime. We use this for both encoding and decoding. This solves an old and annoying issue with Go's stdlib's decoder, with [loss of contrast and muted colors](https://github.com/gohugoio/hugo/issues/8879) in some photos, but it also means that you don't need the extended version of Hugo to handle WebP images. And, drum roll, we now also support animated WebP, including converting to and from animated GIFs.
* For MacOS, we now build signed and notarised `pkg` installers.
Also:
* The Asciidoctor integration is greatly improved.
* New template funcs [urls.PathUnescape](https://gohugo.io/functions/urls/pathunescape/) and [urls.PathEscape](https://gohugo.io/functions/urls/pathescape/).
* [openapi3.Unmarshal](https://gohugo.io/functions/openapi3/unmarshal/) now support external refs (including remote refs).
## Notes
* tpl/css: Deprecate libsass in favor of dartsass (note) 9937a5dc @bep #14261
* Build Order: Hugo builds sites based on the sorted dimensions (see below). In earlier versions, we built the sites starting with the default content language. This change is also reflected in the sort order of `.Site.Sites` to make it consistent with `.Site.Languages`.
* Sort Order: The dimensions are sorted as follows, which affects build order and complement selection:
* languages: By weight, then by name.
* versions: By weight, then by semantic versioning (descending).
* roles: By weight, then by name.
* Deprecations:
* The lang option on mounts (https://gohugo.io/configuration/module/#mounts) and segments
(https://gohugo.io/configuration/segments/#segment-definition) is deprecated in favor of the more powerful `sites.matrix`
option.
* File mount `includeFiles` and `excludeFiles` are deprecated in favour of the new files filter, which supports negation.
* Logging: We no longer log warnings about potential duplicate content paths, as this becomes impractical to reason about with a
complex sites matrix.
## Bug fixes
* Fix some outdated front matter b82e496c @bep #14271
* Fix server rebuilds on editing content with Chinese terms e2e64aee @bep #14240
* Fix slow server startup of very big content trees 7a43b928 @bep #14211
* github: Fix "no space left on device" issue in CI b037b930 @bep
* docs: Fix link to CGO wiki page 5af31128 @jordelver
* Fix grammatical error in styleguide.md 62c47407 @bep
* hugolib: Fix recently introduced data race 94a6233a @bep #14140
* docshelper: Fix some YAML serialization issues with sites matrix configuration 22d0c17e @bep #14132
* resources/page: Fix slugorcontentbasename for section pages 25c7c18f @dvdksn #14104
* all: Fix some benchmarks broken by modernize 91eac9e5 @bep #14107
* all: Run modernize -fix ./... 04650ce7 @bep #14107
## Improvements
* resources/images: Don't trust the file extension when decoding JPEG and PNG images 65d43e1d @bep
* Add full filename to image processing error messages if possible 65a76664 @bep #14278
* tailwindcss: Add referece to skipInlineImportsNotFound when import not found in assets da5b1fcf @bep #14273
* Improve error messages for template failures 0637adb2 @bep
* Improve error handling/messages in Hugo Pipes 0bf61353 @bep #14257 #14270
* images: Add a webp test with bg color 573ecb53 @bep
* Encode and Decode using the libwebp library via WASM with animation support 1b4514e0 @bep #10030 #8500 #12843 #8879 #12842
* config/allconfig: Correct error message 429e5720 @jmooring #14259
* tpl: Add missing functions to init files fa7d37f0 @jmooring #14249
* github: Add some known humans to the AI whitelist fae49a22 @bep
* langs/i18n: Prefer languageCode when picking translation file 6be463b5 @bep #14204 #14217
* Add entitlements for WebAssembly for macOS Tahoe 9e24b564 @bep #14220
* testscripts: Move layouts file to new structure 45b67f6c @bep
* resources: Skip integration test if Dart Sass is not installed 5e649eb4 @jmooring
* testing: Replace legacy config.toml with hugo.toml in most tests 3073fd5c @bep
* testing: Port integration tests to new templates structure b9b304a1 @bep
* github: Correct dependabot => dependabot[bot] 8be30ef2 @bep
* config/privacy: Change GoogleAnalytics.RespectDoNotTrack default to true 565a10cb @jmooring #13307
* Add signed and notarized MacOS pkg builds 438f113f @bep #14135
* Upgrade to Go 1.25.4 dab54058 @bep
* tpl/urls: Add PathEscape and PathUnescape functions 1a1b062a @jmooring #14209
* Speedup and simplify page assembly for deeper content trees 555dfa20 @bep
* gemini: Remove styleguide.md (for now) 34b0c15a @bep
* github: Reenable Gemini, but no auto code review 9dc38e91 @bep
* github: Partition tests by their root b592d34e @bep
* github: Make the clean commands work 18a2afa5 @bep
* github: Also test the root package (left out in previous commit) 0b0c827d @bep
* github: More disk space saving optimizations 30dc75e6 @bep
* github: Add PR Template 6bc8e6f4 @jmooring
* Adjust benchmark cda4d751 @bep
* tpl/openapi: Add support for OpenAPI external file references 84950ed2 @bep #8067
* github: Skip dependabot for AI Watchdog workflow a8ed6137 @bep
* github: Remove the 386 test step in GitHub test workflow b971b7f9 @bep #14201
* github: Remove test binaries after CI test runs 24210dca @bep
* github: Adjust watchdog run logic (now with correct spelling) 0f94274a @bep
* github: Adjust watchdog run logic (again) 5f9c3a3e @bep
* github: Adjust watchdog run logic 51d77a6c @bep
* github: Only run AI Watchdog when the PR is ready for review d25b619c @bep
* Update aiwatchdog.yml 4a76d8c6 @bep
* Update aiwatchdog.yml d837eff0 @bep
* Update aiwatchdog.yml 323e306b @bep
* github: Add label to AI suspects and do not fail when confident 2047638a @bep
* github: Adjust AI Watchdog workflow to make it run PRs from forks 38efb702 @bep
* github: Adjust workflow permissions bdf8b1a9 @bep
* performance: Misc allocation improvements f33c1a3f @bep
* github: Add ai-watchdog workflow and update other workflows' versions 56d7925a @bep #14147
* tpl/collections: Improve collections.D c6b6910a @jmooring #14143
* Optimize memory allocations for sites matrix vector stores ca402540 @bep
* gemini: Disable auto PR codereviews for now 44b5f13f @bep
* Update styleguide.md 2c6574eb @bep
* Add gemini setup files 60c4245e @bep
* static: Preserve .gitignore and .gitattributes in --cleanDestinationDir 5e6b269c @Ahamed1846 #14097
* hugolib: Improve performance of content trees with many sections 26f31ff6 @bep
* Add a site assembly benchmark test for a deeper site structure with more sections and pages 606415ec @bep
* sitesmatrix: Clary default dimension values dc2f6ae2 @bep
* Run go mod tidy to clean up go.mod and go.sum a0944ac7 @bep
* testing: Rewrite all the old style integration tests to txtar style tests a2469d50 @bep
* hugolib: Delete some old integration tests e24b604c @bep
* testing: Revise usage of b.N and b.Loop() in benchmarks 4c7a78f5 @bep
* Add roles and versions as new dimensions (in addition to language) 264022a7 @bep #519 #13680 #13663 #13776 #13855 #13648 #13996 #14001 #14031 #13818 #13196
* Update CONTRIBUTING.md ff0f67ea @bep
* hreflect: Cache reflect method lookups used in collections.Where and others e9bda21c @bep
* all: Simplify the reflect usage 3893e705 @bep
## Dependency Updates
* build(deps): bump github.com/goccy/go-yaml from 1.19.0 to 1.19.1 39649dce @dependabot[bot]
* build(deps): bump github.com/alecthomas/chroma/v2 from 2.21.0 to 2.21.1 614fb16e @dependabot[bot]
* build(deps): bump github.com/aws/aws-sdk-go-v2/service/cloudfront 33542d39 @dependabot[bot]
* deps: Upgrade github.com/alecthomas/chroma/v2 v2.20.0 => v2.21.0 588d20b3 @bep #14266
* build(deps): bump github.com/aws/aws-sdk-go-v2 from 1.40.1 to 1.41.0 b3373029 @dependabot[bot]
* build(deps): bump github.com/evanw/esbuild from 0.27.1 to 0.27.2 e6a3f1d6 @dependabot[bot]
* build(deps): bump golang.org/x/image from 0.33.0 to 0.34.0 364d237b @dependabot[bot]
* build(deps): bump golang.org/x/tools from 0.39.0 to 0.40.0 079f3eb8 @dependabot[bot]
* build(deps): bump github.com/tdewolff/minify/v2 from 2.24.7 to 2.24.8 4e6f2b67 @dependabot[bot]
* build(deps): bump gocloud.dev from 0.43.0 to 0.44.0 dff5e168 @dependabot[bot]
* build(deps): bump github.com/aws/aws-sdk-go-v2/service/cloudfront c82a035b @dependabot[bot]
* build(deps): bump github.com/evanw/esbuild from 0.27.0 to 0.27.1 86b01eda @dependabot[bot]
* build(deps): bump github.com/aws/aws-sdk-go-v2 from 1.40.0 to 1.40.1 9e7182e9 @dependabot[bot]
* build(deps): bump github.com/spf13/cobra from 1.9.1 to 1.10.2 cf3ad62c @dependabot[bot]
* build(deps): bump github.com/goccy/go-yaml from 1.18.0 to 1.19.0 bf421386 @dependabot[bot]
* build(deps): bump github.com/olekukonko/tablewriter from 1.1.1 to 1.1.2 57fecb6b @dependabot[bot]
* build(deps): bump github.com/JohannesKaufmann/html-to-markdown/v2 6d0ab6a3 @dependabot[bot]
* build(deps): bump github.com/aws/aws-sdk-go-v2/service/cloudfront 0de8f860 @dependabot[bot]
* build(deps): bump github.com/aws/aws-sdk-go-v2/service/cloudfront 2b337cd2 @dependabot[bot]
* build(deps): bump golang.org/x/image from 0.32.0 to 0.33.0 cc61d00d @dependabot[bot]
* build(deps): bump golang.org/x/crypto from 0.43.0 to 0.45.0 8ef2c619 @dependabot[bot]
* build(deps): bump github.com/tdewolff/minify/v2 from 2.24.5 to 2.24.7 b9168803 @dependabot[bot]
* build(deps): bump github.com/aws/aws-sdk-go-v2/service/cloudfront 26804673 @dependabot[bot]
* build(deps): bump golang.org/x/tools from 0.38.0 to 0.39.0 8ce80f75 @dependabot[bot]
* build(deps): bump github.com/tetratelabs/wazero from 1.10.0 to 1.10.1 4baa95ba @dependabot[bot]
* build(deps): bump github.com/bits-and-blooms/bitset b81861fd @dependabot[bot]
* build(deps): bump github.com/olekukonko/tablewriter from 1.1.0 to 1.1.1 15cce89e @dependabot[bot]
* build(deps): bump golang.org/x/text from 0.30.0 to 0.31.0 187e683b @dependabot[bot]
* build(deps): bump github.com/evanw/esbuild from 0.25.12 to 0.27.0 432078a6 @dependabot[bot]
* build(deps): bump google.golang.org/api from 0.251.0 to 0.255.0 38608c7c @dependabot[bot]
* build(deps): bump github.com/aws/aws-sdk-go-v2/service/cloudfront d75f0dc6 @dependabot[bot]
* build(deps): bump github.com/tetratelabs/wazero from 1.9.0 to 1.10.0 579362ef @dependabot[bot]
* build(deps): bump github.com/evanw/esbuild from 0.25.11 to 0.25.12 0e8f88fa @dependabot[bot]
## Build Setup
* release: Skip pushing stable and docs update for pre-releases c1cc65fc @bep
* release: Support alpha, beta, and RC releases 66307592 @bep
* snap: Address snapcraft deprecations 596517a2 @jmooring
## Documentation
* markup/asciidocext: Improve Asciidoctor integration 3d21b068 @jmooring #9202 #10183 #10473 #14160
* hugolib/doctree: Simplify lock setup in SimpleThreadSafeTree to reduce read allocation fee09576 @bep
* github: Update asciidoctor-diagrams extension and add GoAT 9d80c397 @jmooring
* markup/asciidocext: Support boolean document attributes bca171b6 @jmooring #14138
* github: Allow AsciiDoc content in tests to render Ditaa diagrams 9289aa43 @jmooring
* commands: newDocsHelper encode integers as ints in generated YAML 0efcb24c @GrigoreAlexandru #14122
* github: Allow AsciiDoc content in tests to render diagrams 2c80dee3 @jmooring