Blog: Theme Management

Level 2 (Topic) — Blowfish versioning, pinning, overrides.

Concept

The blog uses the Blowfish Hugo theme as a Git submodule. The theme is pinned to a specific version rather than tracking master, ensuring reproducible builds.

Git Submodule

The theme is managed as a submodule at themes/blowfish/:

git submodule add https://github.com/nunocoracao/blowfish.git themes/blowfish

The submodule is checked out recursively by the GitHub Action during build.

Version Pinning

The theme is pinned to a specific tag. The current version is v2.96.0 (with a soft-upgrade to v2.101.0 being deferred due to non-blocking site.Data deprecation cleanup).

Upgrading:

  1. cd themes/blowfish && git fetch && git checkout <tag>
  2. Test locally with hugo server --buildDrafts
  3. Commit the new submodule reference

Theme Overrides

Local template overrides live in layouts/. Hugo checks the layouts/ directory before falling back to the theme. Currently used for:

  • Custom partial overrides
  • Middleware-specific adjustments

Configuration

Blowfish is configured through config/_default/params.toml. Key sections:

  • [header]: Layout style (fixed-fill-blur)
  • [homepage]: Layout (background with background image)
  • [article]: Hero image, TOC, comments, reading time
  • [cusdis]: Comment system settings
  • [footer]: Menu, copyright, appearance switcher

See Also