v4.0.1

What's Changed

• fix(image): correct permalink handling for images placed in static folder by @CaiJimmy in #1330

Full Changelog: v4.0.0...v4.0.1

v4.0.0

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.

Migration guide: https://stack.cai.im/guide/upgrade-to-v4

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)
• Built-in GDPR cookie consent support (#1216)
• Consent-aware comment loading (#1216)
• Better taxonomy, term, archive, and list page behavior (#1268, #1250, #1314)
• Optional article tag display in list pages (#1270)
• Optional sorting by lastmod (#1250)
• Collapsible table of contents on smaller screens (#1245)
• Styled Markdown alerts (#1221)
• Support for more comment providers, including Comentario (#1088)
• Custom canonical URL support (#1267)

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.0 or newer.

Hugo Modules import path

If you install Stack through Hugo Modules, the module path is now:

[[module.imports]]
    path = "github.com/CaiJimmy/hugo-theme-stack/v4"

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

featuredImageField was removed

PR: #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 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.

Sidebar avatar config changed

PR: #1247

The sidebar avatar is now just a string path instead of a nested object, and the old local flag is gone.

Before:

params:
  sidebar:
    avatar:
      enabled: true
      local: true
      src: img/avatar.png

Now:

[sidebar]
    avatar = "img/avatar.png"

Favicon path behavior changed

Related PR: #1246

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.

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’s build.list behavior.

Before:

hidden: true

Now:

build:
  list: never

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.html
• layouts/_default/single.html -> layouts/single.html
• layouts/_default/archives.html -> layouts/archives.html
• layouts/index.html -> layouts/home.html
• layouts/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 .Pre were dropped

Related 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:

1. Upgrade Hugo to 0.157.0 or newer.
2. If you use Hugo Modules, switch the import path from .../v3 to .../v4.
3. Compare your existing config against the new baseline in config/_default/params.toml and the official upgrade guide: Upgrade to v4.
4. Remove old config that no longer exists:
   • featuredImageField
   • defaultImage.*
   • opengraph.local / opengraph.src
   • imageProcessing.cover.enabled
   • the old nested sidebar.avatar object
5. If you override i18n files, convert or refresh them against the new TOML files.
6. If you use zh-cn, zh-hk, or zh-tw, update those language codes to the new forms.
7. If you were using hidden: true, migrate that to Hugo build.list.
8. If you store your favicon in static, move it to assets and update the config path if needed.
9. If you override layouts, move them to the new paths before assuming something is broken.
10. Double-check image-heavy pages, taxonomy pages, archives, search, and RSS after the upgrade.
11. 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.
...

v4.0.0-beta.15

What's Changed

• fix: ensure taxonomy widget title is only linked if a taxonomy page exits by @CaiJimmy in #1314

Full Changelog: v4.0.0-beta.14...v4.0.0-beta.15

v4.0.0-beta.14

What's Changed

• fix: skip inaccessible images to avoid build failure by @jin-li in #1301
• refactor: remove custom scrollbar styles and related variables by @CaiJimmy in #1304

New Contributors

• @jin-li made their first contribution in #1301

Full Changelog: v4.0.0-beta.13...v4.0.0-beta.14

v4.0.0-beta.9

What's Changed

• fix: use IsImageResourceWithMeta to check whether image has width / height attributes by @CaiJimmy in #1285

Full Changelog: v4.0.0-beta.8...v4.0.0-beta.9

v4.0.0-beta.13

What's Changed

• chore: Remove featuredImageField from configuration by @CaiJimmy in #1298
• fix: check if resource exists before accessing .RelPermalink by @CaiJimmy in #1299

Full Changelog: v4.0.0-beta.12...v4.0.0-beta.13

v4.0.0-beta.12

What's Changed

• refactor: simplify article-list/tile partial context passing by @CaiJimmy in #1295
• fix: do not display the date of term pages by @CaiJimmy in #1296

Full Changelog: v4.0.0-beta.11...v4.0.0-beta.12

v4.0.0-beta.11

What's Changed

• refactor: rename article-footer to article-meta by @CaiJimmy in #1293
• feat: use images.AutoOrient in helper/image by @CaiJimmy in #1294

Full Changelog: v4.0.0-beta.10...v4.0.0-beta.11

v4.0.0-beta.10

What's Changed

• refactor: cleanup stylesheet by @CaiJimmy in #1286
• refactor: add standardized spacing variables and more style cleanup by @CaiJimmy in #1287
• feat: hide search results container if no keyword is given by @CaiJimmy in #1288
• feat(widgets): link widget titles to their respective pages by @delize in #1277
• refactor: make article-list/compact better for term pages by @CaiJimmy in #1289
• refactor: use helper/image in links.html by @CaiJimmy in #1290
• feat: use thumbnail in section and links image by @CaiJimmy in #1291

Full Changelog: v4.0.0-beta.9...v4.0.0-beta.10

v4.0.0-beta.8

What's Changed

• fix: reading time not displaying in article/components/details partial by @delize in #1278
• fix: keep external image url, and use reflect.IsImageResourceProcessable to check for svg and other non-processable image formats by @CaiJimmy in #1282
• feat: add responsive image support by @CaiJimmy in #1283

Full Changelog: v4.0.0-beta.7...v4.0.0-beta.8