You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Stack v4 is the biggest refresh to the theme in a long time. It brings the codebase up to date with modern Hugo, adds a few long-requested features, and cleans up a lot of old configuration along the way.
TL;DR
Stack v4 requires Hugo 0.157.0+ and Hugo Modules users need to switch to github.com/CaiJimmy/hugo-theme-stack/v4
The theme now uses a cleaner TOML-based config structure, with some old v3 options removed or renamed
Major additions include Mermaid support, better image handling, PhotoSwipe v5, GDPR cookie consent, Markdown alerts, and improved taxonomy/list behavior
The biggest migration work is usually config cleanup, moving template overrides to new paths, and replacing deprecated options like hidden, featuredImageField, and imageProcessing.cover
If you’re on v3 and haven’t customized much, the upgrade should be pretty straightforward. If you’ve overridden templates or relied on older config quirks, plan for a quick review pass.
The following release note has been generated by AI. It's been so long that I can't remember how many things have changed.
What’s new
The biggest change in v4 is that the theme has been updated for newer Hugo versions and the newer template system. That gave us room to simplify a lot of internals and make the theme easier to maintain going forward.
There are also a bunch of user-facing improvements:
Built-in Mermaid support for fenced mermaid code blocks (#1214)
Better image handling, including improved remote image support (#1235), and optional auto-orientation (#1294)
A refreshed gallery experience with PhotoSwipe v5 (#1233)
The theme defaults are now organized as TOML files under config/_default, and the built-in i18n files also moved from YAML to TOML.
You do not have to rewrite your whole site config if you prefer YAML, because Hugo can still read it. But if you copied theme defaults, custom i18n files, or starter config from v3, you should compare them against the new TOML-based structure.
Some language codes changed
Because v4 now leans on Hugo's localized date formatting more heavily, some Chinese language codes were renamed to match Hugo locales:
zh-cn -> zh
zh-hk -> zh-hant-hk
zh-tw -> zh-hant-tw
If you use any of these in defaultContentLanguage, languages, or overridden i18n files, update them during migration.
v3 allowed you to change the front matter key used for article images with featuredImageField. v4 removes that setting and simply expects images to live in image.
Realistically, I don’t think many people were using this, but if you were, you’ll need to rename that field or keep a small custom override on your side.
defaultImage fallback config was removed
The old params.defaultImage.* fallback logic is no longer part of the theme. If your site depended on that behavior, you’ll need to reintroduce it in a custom override.
Default Open Graph fallback image config was removed
The old fallback Open Graph / Twitter image config is no longer supported by the theme. If you relied on opengraph.local or opengraph.src, you’ll want to replace that with your own override logic.
The favicon is now expected to come from the assets folder rather than static.
Example:
favicon = "img/favicon.png"
which points to:
assets/img/favicon.png
Image processing config changed
The old imageProcessing.cover.enabled setting has been replaced by imageProcessing.thumbnail.enabled, and image processing options are a bit more capable now.
Before:
params:
imageProcessing:
cover:
enabled: true
Now:
[imageProcessing.thumbnail]
enabled = true
v4 also adds things like responsive widths for content images and optional auto-orientation.
If you override i18n files, convert or refresh them against the new TOML files.
If you use zh-cn, zh-hk, or zh-tw, update those language codes to the new forms.
If you were using hidden: true, migrate that to Hugo build.list.
If you store your favicon in static, move it to assets and update the config path if needed.
If you override layouts, move them to the new paths before assuming something is broken.
Double-check image-heavy pages, taxonomy pages, archives, search, and RSS after the upgrade.
If you use comments or analytics, test them once with cookies disabled and once with cookie consent enabled.
Most sites should be able to upgrade without too much trouble, but heavily customized setups will probably want to treat this as a proper migration rather than a drop-in version bump.
reacted with thumbs up emoji reacted with thumbs down emoji reacted with laugh emoji reacted with hooray emoji reacted with confused emoji reacted with heart emoji reacted with rocket emoji reacted with eyes emoji
Uh oh!
There was an error while loading. Please reload this page.
Stack v4 is the biggest refresh to the theme in a long time. It brings the codebase up to date with modern Hugo, adds a few long-requested features, and cleans up a lot of old configuration along the way.
TL;DR
0.157.0+and Hugo Modules users need to switch togithub.com/CaiJimmy/hugo-theme-stack/v4hidden,featuredImageField, andimageProcessing.coverIf you’re on v3 and haven’t customized much, the upgrade should be pretty straightforward. If you’ve overridden templates or relied on older config quirks, plan for a quick review pass.
Migration guide: https://stack.cai.im/guide/upgrade-to-v4
What’s new
The biggest change in v4 is that the theme has been updated for newer Hugo versions and the newer template system. That gave us room to simplify a lot of internals and make the theme easier to maintain going forward.
There are also a bunch of user-facing improvements:
mermaidcode blocks (#1214)lastmod(#1250)There’s also a lot of cleanup behind the scenes: more sensible defaults, less template-side fallback logic, and a clearer config structure overall.
Breaking changes
v4 does include a few breaking changes, especially if you’ve been using custom config or overriding theme templates.
Hugo requirement
Stack v4 now requires Hugo
0.157.0or newer.Hugo Modules import path
If you install Stack through Hugo Modules, the module path is now:
If you’re still importing
.../v3, you’ll need to update that.Config and i18n files moved from YAML to TOML
Related PRs: #1228, #1230
The theme defaults are now organized as TOML files under
config/_default, and the built-in i18n files also moved from YAML to TOML.You do not have to rewrite your whole site config if you prefer YAML, because Hugo can still read it. But if you copied theme defaults, custom i18n files, or starter config from v3, you should compare them against the new TOML-based structure.
Some language codes changed
Because v4 now leans on Hugo's localized date formatting more heavily, some Chinese language codes were renamed to match Hugo locales:
zh-cn->zhzh-hk->zh-hant-hkzh-tw->zh-hant-twIf you use any of these in
defaultContentLanguage,languages, or overridden i18n files, update them during migration.featuredImageFieldwas removedPR: #1298
v3 allowed you to change the front matter key used for article images with
featuredImageField. v4 removes that setting and simply expects images to live inimage.Realistically, I don’t think many people were using this, but if you were, you’ll need to rename that field or keep a small custom override on your side.
defaultImagefallback config was removedThe old
params.defaultImage.*fallback logic is no longer part of the theme. If your site depended on that behavior, you’ll need to reintroduce it in a custom override.Default Open Graph fallback image config was removed
The old fallback Open Graph / Twitter image config is no longer supported by the theme. If you relied on
opengraph.localoropengraph.src, you’ll want to replace that with your own override logic.Sidebar avatar config changed
PR: #1247
The sidebar avatar is now just a string path instead of a nested object, and the old
localflag is gone.Before:
Now:
Favicon path behavior changed
Related PR: #1246
The favicon is now expected to come from the
assetsfolder rather thanstatic.Example:
which points to:
Image processing config changed
The old
imageProcessing.cover.enabledsetting has been replaced byimageProcessing.thumbnail.enabled, and image processing options are a bit more capable now.Before:
Now:
v4 also adds things like responsive widths for content images and optional auto-orientation.
Vibrant.js was removed
Related PR: #1236
The theme no longer uses Vibrant.js to extract image colors on the client side. Image-related behavior now relies on Hugo-native processing instead.
Hidden content behavior changed
PR: #1249
In v3, Stack commonly filtered content with
hidden: true. In v4, this has been moved over to Hugo’sbuild.listbehavior.Before:
Now:
This affects things like homepage lists, archives, pagination, RSS, related content, and search indexing.
Layout override paths changed
Related PR: #1232
If you override theme templates in your site, this is the part worth checking most carefully.
The theme has been reorganized to follow newer Hugo layout conventions, including moves like:
layouts/_default/list.html->layouts/list.htmllayouts/_default/single.html->layouts/single.htmllayouts/_default/archives.html->layouts/archives.htmllayouts/index.html->layouts/home.htmllayouts/partials/...->layouts/_partials/...layouts/shortcodes/...->layouts/_shortcodes/...layouts/_default/_markup/...->layouts/_markup/...If you have old overrides in the previous locations, they won’t be picked up anymore.
Sidebar menu icons via
.Prewere droppedRelated PR: #1271
If your custom menu icons were injected through
.Pre, you’ll need to reconfigure or remove that usage.Migration notes
If you’re upgrading from v3, this is the path I’d recommend:
0.157.0or newer..../v3to.../v4.featuredImageFielddefaultImage.*opengraph.local/opengraph.srcimageProcessing.cover.enabledsidebar.avatarobjectzh-cn,zh-hk, orzh-tw, update those language codes to the new forms.hidden: true, migrate that to Hugobuild.list.static, move it toassetsand update the config path if needed.Most sites should be able to upgrade without too much trouble, but heavily customized setups will probably want to treat this as a proper migration rather than a drop-in version bump.
Detailed changelog
RelPermalinkfor internal links by @CaiJimmy in refactor: UseRelPermalinkfor internal links #1231<select>in i18n switch by @CaiJimmy in style: remove vendor style of<select>in i18n switch #1238params.tomlby @CaiJimmy in refactor: move default parameter values from template logic toparams.toml#1244.Site.Home.RelPermalinkfor home page links in the sidebar by @CaiJimmy in refactor: use.Site.Home.RelPermalinkfor home page links in the sidebar #1248Params.hiddento the newbuild.listparameter. by @CaiJimmy in refactor: migrate page visibility control fromParams.hiddento the newbuild.listparameter. #1249mutedattribute and refineautoplaycondition for video shortcode by @CaiJimmy in feat: addmutedattribute and refineautoplaycondition for video shortcode #1256taxonomywidget by @CaiJimmy in refactor: create a generictaxonomywidget #1268article/components/detailspartial by @delize in fix: reading time not displaying inarticle/components/detailspartial #1278article-list/compactbetter for term pages by @CaiJimmy in refactor: makearticle-list/compactbetter for term pages #1289helper/imageinlinks.htmlby @CaiJimmy in refactor: usehelper/imageinlinks.html#1290article-footertoarticle-metaby @CaiJimmy in refactor: renamearticle-footertoarticle-meta#1293images.AutoOrientinhelper/imageby @CaiJimmy in feat: useimages.AutoOrientinhelper/image#1294article-list/tilepartial context passing by @CaiJimmy in refactor: simplifyarticle-list/tilepartial context passing #1295featuredImageFieldfrom configuration by @CaiJimmy in chore: RemovefeaturedImageFieldfrom configuration #1298.RelPermalinkby @CaiJimmy in fix: check if resource exists before accessing.RelPermalink#1299.Site.Datawithhugo.Databy @powerfullz in fix: replace deprecated.Site.Datawithhugo.Data#1322New Contributors
Full Changelog: v3.34.2...v4.0.0
This discussion was created from the release v4.0.0.
All reactions