↓ Skip to main content

How I Customised the Blowfish Hugo Theme Without Forking It

2379 words·12 mins· loading · loading ·
Table of Contents

This site is built with Hugo and the Blowfish theme by Nuno Coração. If you’ve seen a few Blowfish sites, this one probably doesn’t look like them: a two-column homepage hero, numbered project cards, an orange palette with a glow behind every page, a slim rail instead of a table-of-contents sidebar, and pages that cross-fade into each other.

None of that comes from a fork. The theme sits untouched in a Git submodule, and everything is done with Hugo’s own override mechanism. This post covers how it’s put together, what each change is, and the things that broke along the way, because the upgrades taught me more than the design did.


Why Blowfish, and why orange
#

I built the first version of this site a few years ago, while I was learning Go and getting to know Hugo. Blowfish was fast and already polished, so it was an easy choice to start with. It turned out to be the right one. It isn’t as customisable as a site built from scratch with something like Astro, but it does everything I need here, and the rest of this post shows how far it can be pushed without a fork.

The orange is a personal choice. Orange, or saffron, has always held a deep meaning for me: it’s an inspiring colour, and it carries a feeling of progress. Blowfish’s fire scheme was the closest match, so I built the rest of the design around it.


At a glance
#

Theme Blowfish v3.10.0, as a Git submodule, never edited
Hugo 0.168, extended, with Dart Sass
Overrides 33 template files under layouts/, 12 SCSS feature files, one appearance.js
Colour scheme Blowfish’s fire, with the remaining blue and indigo hardcodes replaced by the primary colour
Build A two-stage Dockerfile: Hugo’s official image builds, an unprivileged NGINX serves
Page weight Homepage 1351 KB → 412 KB after the performance pass

The rule: override the smallest file, never edit the theme
#

Hugo looks for a template in the site’s own layouts/ before it looks in the theme. A file at layouts/partials/head.html replaces the theme’s partials/head.html, and nothing else changes. So the theme stays a clean submodule, pinned to a commit, and updating it is a one-line change.

The catch is that an override is a copy. When the theme improves that file, your copy doesn’t. I learned this the hard way (more below), so the rule is: override the smallest partial that does the job, keep the diff against the theme as small as possible, and re-check every override on every theme upgrade.

layouts/
├── _default/_markup/          # render hooks: code blocks, images
├── partials/
│   ├── home/custom.html        # the homepage
│   ├── article-link/           # post, project and related-post cards
│   ├── posts/series-card.html  # series cards on /posts/
│   ├── series/series_base.html # the "part of a series" box
│   ├── toc.html                # the progress rail
│   ├── og-image.html           # generated share cards
│   └── head.html, footer.html, social-meta.html, ...
├── posts/list.html             # blog index grouped by series
├── projects/list.html          # projects grid
└── shortcodes/                 # button, github, timelineItem

Styles follow the same idea. Instead of one long custom.css, assets/css/custom.scss pulls in feature files (_cards, _codeblocks, _toc-rail, _transitions, _typography and so on) with Dart Sass @use, and head.html compiles it. Each feature’s CSS lives next to its name, so I can find it again a month later.


Look and feel
#

  • Palette. Blowfish’s fire scheme, dark by default. A few templates had hardcoded indigo and blue utility classes that ignored the scheme; those now use the primary colour, so the whole site follows the palette.
  • An ember glow on every page. A background SVG with a transparent base, so it tints light and dark mode alike. One fix here was subtle: Blowfish paints the page colour on <body>, which is width-capped. If anything gives <html> its own background (Dark Reader does), the body colour stops reaching the canvas and paints a dark box over the glow. The colour now lives on <html>, and <body> is transparent.
  • The logo is traced to an inline SVG coloured from the palette, which fixed the surname disappearing in light mode.
  • Fonts are self-hosted variable woff2 files (Inter, Plus Jakarta Sans, Fira Code and Satisfy), with the two main faces preloaded. No Google Fonts requests.
  • A pill navigation bar with an active state and a Contact button, on Blowfish’s floating header.

The homepage
#

Blowfish ships several homepage layouts; this one is layout = "custom", which hands the page to layouts/partials/home/custom.html. The copy lives in content/_index.md front matter, so changing the headline doesn’t mean touching a template.

  • A two-column hero: a large headline with an orange-to-rose gradient accent, a photo byline, call-to-action buttons and social icons on the left; the latest post as a card on the right. On a phone the photo stacks above the intro.
  • A stat strip computed from the content at build time, so the numbers can’t go stale.
  • Featured projects (any project with featured: true in front matter) above recent writing, each with its own “all” link. Recent writing skips the post already shown in the hero.
  • Gradient fallback banners for posts without a cover image, instead of an empty grey slab.

Cards
#

Posts
#

Post cards show an eyebrow (the topic), the summary, a NEW or FEATURED badge where it applies, reading time and at most three tags. Article headers cap tags at five.

Projects
#

Project cards are the most custom part of the site: a numbered gradient banner that cycles orange, amber and rose, a label pill, the title and summary, tech chips, and Source and Live buttons. They read four front-matter fields of my own:

YAML
label: "Homelab · Platform"
tech: ["K3s", "Argo CD", "Terraform", "Tailscale", "Proxmox"]
repo: "ChetanThapliyal/Project-Aether"      # becomes the Source button
demo: "https://status.chetan-thapliyal.cloud" # becomes the Live button

Two details took more thought than they look:

  • Chips fit on one row. The card shows up to three tech chips, stopping early once their names pass about 26 characters, and folds the rest into a +N chip whose tooltip lists them. Long names like “Azure Functions” would otherwise wrap and push the buttons out of line.
  • The year comes from the project’s date. Folders are named like 202601-Project-Aether, and the card used to take the year from that prefix. A front-matter date now wins, so renaming a folder (which would change its URL) is never needed to fix a year:
GO-HTML-TEMPLATE
{{ $year := substr (path.Base $dir) 0 4 }}
{{/* A front-matter date wins over the folder name's year prefix. */}}
{{ if not $p.Date.IsZero }}{{ $year = $p.Date.Format "2006" }}{{ end }}

Series
#

The blog index groups posts by series, and each series gets a card. The stock lookup took the cover from the newest post, which left one series as an empty box when that post’s cover was a bundle image rather than a URL. The card now resolves its cover in order: the series’ own bundle (content/series/<name>/, any image named like feature, cover, thumbnail or background), then the newest post’s, and resizes local images to the card size.

The “this article is part of a series” box is overridden too, so it shows the series’ real title instead of its slug and numbers the parts from series_order.


Reading an article
#

  • A progress rail instead of a sidebar. On desktop, the table of contents is a slim column of dashes fixed in the right margin. It tracks the section you’re reading and expands into the full list on hover or focus. The reading column stays centred. On mobile, the theme’s collapsible contents block is unchanged.
  • Code blocks with a header. A render hook adds a bar with the file name (from title="..." on the fence) or the language, and a copy button that’s always visible, in light and dark variants.
  • Related posts as compact rows. Three cards squeezed into the article column were about 220 px wide each, and their titles inherited article-heading size, so each card ran six to eight lines. Each related post is now one row: a small cover, the title clamped to two lines, reading time and first tag.
  • A cheaper scroll effect. Blowfish’s article hero blurs the background as you scroll, using backdrop-filter, which re-blurs the whole viewport every frame. It’s now a near-opaque tint that fades in the same way.
  • Diagrams follow the theme. My appearance.js override predated Blowfish’s Mermaid support, so Mermaid drew in its default light theme on a dark page. The override now initialises Mermaid with the site palette and re-renders it when you switch appearance.

Page transitions
#

Navigation uses the browser’s cross-document View Transitions API, with no JavaScript framework involved. Pages cross-fade in under a fifth of a second, the floating header stays still, and a card’s cover image morphs into the article’s hero when you open it (and back again when you go back).

SCSS
@media (prefers-reduced-motion: no-preference) {
    @view-transition {
        navigation: auto;
    }
}

/* The floating header is identical on every page: keep it still. */
header > .fixed:has(.main-menu) {
    view-transition-name: site-header;
}

The cover morph pairs the card image and the hero image with the same view-transition-name, set on the pageswap and pagereveal events. It’s off for anyone who asks for reduced motion, and browsers without support simply navigate normally.


Share cards and feeds
#

Every page gets its own 1200×630 share card, generated at build time with Hugo’s image filters: a label (series and reading time, or “Project · 2026”) in orange Inter, and the title in Plus Jakarta Sans, over a branded base image with my signature. Long titles wrap by an estimated characters-per-line budget and step down in size. The site’s own Open Graph and Twitter tags replace Hugo’s internal templates, so each page has exactly one og:image.

The RSS feed adds media:thumbnail, so feed readers show cover images.


Performance
#

Measured on a local build with the cache disabled, scrolling each page to the end:

Page Before After
Homepage 1351 KB 412 KB
A post 1638 KB 611 KB
A project page 1755 KB 684 KB
  • Every resized image is WebP (quality 82): card, hero and author templates, the theme’s resize helper, and the Markdown image render hook. Click-to-zoom is capped at a 1920 px WebP instead of the full original.
  • Self-hosted fonts, preloaded, as above.
  • Firebase loads only where view or like counters appear, which is 51 of 325 pages, down from 199.
  • 84 unreferenced images deleted from the repo (about 53 MB): trial backgrounds, unused logo variants, old résumé PDFs.

What broke on the way from v2 to v3
#

The site jumped from Blowfish v2.97 to v3.8 (578 upstream commits), and later to v3.10. Upstream v3 is backwards compatible, and for the theme itself that held. The trouble was all on my side.

Stale overrides were quietly undoing v3. Two of my overrides, head.html and a card partial, were full copies of the v2 files with a small change grafted on. They’d never been rebased, so they silently removed about fifteen v3 improvements: hreflang links, reading progress, image zoom, newer meta tags, fetchpriority and alt on card images, and they still loaded a script v3 had deleted. Rebased onto v3, each became a three-line diff against the theme. An override you haven’t re-read since the last upgrade is a regression waiting to happen.

Some overrides were noise. Two shortcode overrides differed from the theme only in indentation. They were deleted, and the theme’s versions are inherited again.

A redesign that never rendered. The theme submodule had uncommitted edits to the timeline shortcode that looked like a deliberate card redesign. They were dead code: my own layouts/ copy of the same shortcode takes precedence, so the edited theme file was never used. Keep the submodule clean, and edit only your own copies.

The Hugo version range. The theme declares the Hugo versions it supports, and my own module.toml contradicted it (extended = false, a very old minimum). It now matches the theme, currently Hugo 0.163 to 0.169.

The build image. Blowfish needs Hugo’s extended edition. In the hugomods/hugo images, the tags you’d guess (reg-*, std-*) are not extended and fail on SCSS with “you need the extended version”. The theme’s newer minimum then went past the newest hugomods release altogether. The build now uses Hugo’s official image, ghcr.io/gohugoio/hugo, which is extended and includes Dart Sass:

Dockerfile
FROM ghcr.io/gohugoio/hugo:v0.168.0 AS hugo-builder
WORKDIR /src
COPY --chown=hugo:hugo . .
RUN hugo --minify

# Unprivileged NGINX: runs as uid 101 and listens on 8080, so no root at runtime
FROM nginxinc/nginx-unprivileged:1.28-alpine
COPY --from=hugo-builder /src/public /usr/share/nginx/html
USER 101
EXPOSE 8080

LibSass to Dart Sass. Hugo deprecated its built-in LibSass. Moving to Dart Sass meant switching the SCSS @import rules to @use; the compiled CSS came out byte-identical, which is the easiest way to know a migration changed nothing.

Root-owned build output. Running Hugo in a container with the repo bind-mounted (docker run -v "$PWD":/src) wrote public/ and resources/_gen/ as root, and the local hugo server then failed with permission errors. Pass --user "$(id -u):$(id -g)", or use docker build, which never writes to the host.

The GitHub repo cards call GitHub’s API without authentication, which allows 60 requests an hour. A few rebuilds in a row use that up, and the cards go blank until the hour resets. Worth knowing before you put a dozen of them on one site.


If you’re customising Blowfish
#

  • Keep the theme as a clean submodule and override files in your own layouts/. Never edit the theme directory.
  • Override the smallest partial that does the job, and keep a note of what you changed in each.
  • Re-read every override on every theme upgrade. Diff it against the new theme file; a copy that’s drifted is silently removing features.
  • Put your own front-matter fields to work (label, tech, repo, demo here) instead of overloading tags.
  • Measure before and after a performance change. WebP everywhere and self-hosted fonts did most of the work here.
  • Match your Hugo version to the theme’s declared range, and use an image that’s really the extended edition.

Blowfish made all of this possible by being so easy to extend without forking. If you have questions about any of these changes, the site’s source layout above is the map, and I’m happy to answer them.