The fix was mostly plumbing. My img shortcode was handing the raw src straight to the <img> tag, so Hugo never got a look in. Everything now goes through one partial that resizes to the width it actually displays at, re-encodes to WebP and emits a srcset, plus width and height so the layout stops jumping around while things load. Markdown images get the same treatment through a render hook. The awkward bit: images under static/ aren’t resources, so Hugo can’t touch them. A second mount in hugo.toml fixes that without breaking any existing URLs.

While I was in there I dealt with the JavaScript. Every page was carrying all seven inline scripts, even the 90-odd pages with no code blocks, no zoomable images and no locked series titles. Those three now load only where they actually do something. The two that genuinely run everywhere moved into one small fingerprinted bundle, so your browser fetches it once for the whole visit instead of re-reading it on every page. I also finally turned on HTML minification, which I’d apparently never bothered with.

Where it landed:

That last one is about 46 times smaller. Nothing changed visually, which was the whole point. The sparks still spark and the locked titles still scramble.

One last silly thing. I added a new short code to style “Plant Smart” as “Plant🌱Smart”. Fun!

Some background.#

For three years every plant page on Plant🌱Smart ended with the same two phone numbers and both of them were for the US. That never really sat right with me. I even flagged it as roadmap work when I rebuilt the site, then left it sitting there. The site’s whole reason for existing is for the moment your cat eats something and you need an answer now. For most of the people who land there from a search engine, I was answering with a number they can’t dial. So, I recently sat down to address that gap, assuming I’d spend a few minutes filling in a table of hotlines and be done with it.

Every single country had a speed bump.#

• Sweden’s poison centre stopped answering questions about animals in July 2018 because the human call volume got too high.
• The Dutch line only takes calls from vets, so if you’re a pet owner in Rotterdam, the correct advice is “ring your vet and let them ring the line”, which is not a phone number at all.
• Belgium answers animal calls only during the day and says outright on its own site that it isn’t funded for animal work.
• The Australian helpline I’d have sworn was free actually starts at $75. This is a bit embarrassing because I live here and should know this.
• The UK’s fee changes depending on the time of day you call.
• The ASPCA doesn’t publish its consultation fee anywhere on its own page, so the figure everyone quotes online comes from third parties.

The list goes on.

I’d have got at least half of these wrong from memory, which is a genuinely unsettling thing to realise about emergency information.

Once again, I had to collate a bunch of disparate data and create a shape to support it before munging it all together. Every entry in the hotlines list now cites the operator’s page it came from and the date I read it which is the same rule I put on the plant records in the last post. A Python script holds the whole list and nags me when an entry goes over a year old and it runs as part of the automated deployment. So, the build gives me a big’ole bonk on the nose whenever the list goes stale.

The boring technical stuff.#

The engineering ended up being the easy half and mostly a matter of deciding what fails safely. Hugo writes every country into the HTML as a partial. A small script then lifts the relevant one out and folds the rest away. It guesses in order: a country you’ve pinned, then the location filter if it names exactly one country, then your browser locale.

It never asks permission for anything, because a permission prompt at 2am is the last thing you need while you’re panicking about your pet. And, personally, I hate browser prompts asking for location tracking. Hard pass. If the script doesn’t run, or if the service worker hands you a stale page, you get all countries instead of the wrong one.

There’s also a new emergency page for the first five minutes before you get through: what to do, what not to do and what they’ll ask you. The guidance follows the ASPCA and the Pet Poison Helpline which is also cited and linked. After all, the one thing I’m definitely not qualified to write is clinical advice.

Another free gift: the hotlines API.#

There’s really no obvious centralised place online that collates all this information into a single data set. I’ve at least done the work of bootstrapping the handful of most common countries that have helplines and the list will definitely grow over time. So, I’ve exposed a new “hotlines” API endpoint with its own documented shape.

{
    "countries": {
        // ... more countries ...
        "US": {
            "checked": "2026-09-10",
            "name": "United States",
            "services": [
                {
                    "audience": "owner",
                    "display": "(888) 426-4435",
                    "fee": "A consultation fee applies",
                    "hours": "24 hours, every day",
                    "org": "ASPCA Animal Poison Control Center",
                    "source": "https://www.aspca.org/pet-care/animal-poison-control",
                    "tel": "+18884264435"
                },
                {
                    "audience": "owner",
                    "display": "(855) 764-7661",
                    "fee": "$89 for each incident",
                    "hours": "24 hours, every day",
                    "org": "Pet Poison Helpline",
                    "source": "https://www.petpoisonhelpline.com/about/",
                    "tel": "+18557647661"
                }
            ]
        }
    },
    "notice": "Emergency telephone numbers for animal poisoning. Each country cites the operator page the entry came from and the date a person read it. Services close and numbers change, so check an entry before you rely on it. Coverage is not global. A country in this file with an empty services list has been checked and has no service an owner can call. A country that is absent has not been checked.",
    "updated": "2026-09-10"
}

I felt wrapping it in an envelope was the correct approach here. It leads with the notice and the date I last changed anything. A .countries object follows, keyed by ISO 3166-1 alpha-2 code. At the very least, it gives me room to change a country’s metadata later without breaking the top-level shape.

The audience field on each service is what carries the Dutch problem into the data. It reads either owner or vet. A vet entry means the number exists but you can’t ring it yourself, so the entry tells you to phone your vet and let them make the call.

Anyway, along with some stylistic changes and code cleanup, that’s pretty much all there is to it for this update. I’ll be giving Plant🌱Smart a rest for a bit while all the changes settle in. This gives me some time to work on other fun things!

Enjoy, nerds!

Well, I finally did the thing.

Three and a half years ago I wrote Why I Built Plant🌱Smart. A free and searchable database of plants that are toxic to pets. I built it over a holiday break to answer a simple question, “Can I bring this plant home without endangering the fluffy little gremlin that runs our household?” It was also my excuse to learn SvelteKit, TypeScript, TailwindCSS and Vite, because my frontend peers wouldn’t shut the hell up about them.

The site then chugged along quietly and untouched for years, which sounds like a compliment to its architecture and very much is not one to the maintainer.

The toolchain aged like fine milk.#

The thing no one really thinks about when they build something like this with shiny new frontend tools is that it doesn’t rust, it curdles. When I finally came back to give Plant🌱Smart a fresh coat of paint, the build no longer ran. Not “a few deprecation warnings” didn’t run. It didn’t run at all. Two years of an unattended package.json had fermented into something of a cheese-like consistency.

My original requirements list from 2022 said the site must be fast, static, ( almost ) free to run and open with its data. Nowhere did it say “must still compile in two years”.

So, I decided to spend a few weeks off and on to throw out the toolchain and give it a much-needed refresh. Just like this site, Hugo now builds the entire thing. There’s a single hand-written stylesheet and a few small scripts of delicious vanilla JavaScript. No npm install, because there is no longer anything to install. If I disappear for another two years ( likely ), the site will build exactly the same the day I come back.

First things first, absolute parity.#

The rebuild had one rule that saved me from myself: the first pass had to be a 1:1 replica of the old site. It needed the same pages, filters, URLs and quirks. The pass was meant to be boring on purpose. I had to resist the temptation of doing both the replatforming and redesigning all in one go.

My primary constraint was the plant data. Plant🌱Smart’s whole gimmick is what I called a “dumb API”. The entire primary database lives in one JSON file with other, smaller, supplemental files you could use as lookup tables. Since this was all hosted on Cloudflare’s CDN it was effectively free to use for others without keys or annoying rate limits. The old derivations were originally done by a pile of Go magefiles. The new site had to reproduce them exactly, down to the deliberately unsorted first-appearance ordering, or every downstream consumer would notice.

Hugo, it turns out, can do all of it. A content adapter reads the database and births every plant page directly with no intermediate files. A handful of templates re-implement the old Go derivation logic and regenerate the API on every build. I diffed the generated files against the originals and they came back value-identical on the first honest attempt.

Then came my favourite commit of the whole project:

retire the sveltekit stack: remove src, magefiles and the node toolchain
566 files changed, 112 insertions(+), 9905 deletions(-)

I deleted nearly ten thousand lines and the site did more than before. This is every developer’s favourite kind of commit.

I made the site cute on purpose.#

With the replica shipped, the redesign could actually be fun. The old site was fine but it was very much “2022 Tailwind starter” vibe. A lot of cool greys, hard shadows and gradients on anything that stood still. Meanwhile the logo, a randomised squishy little pastel potted plant with a face, deserved better surroundings.

So, I set out to make the logo the design brief. Cream paper instead of white with warm espresso ink instead of a dull grey. Sage and moss greens with honey and clay accents were all lifted straight from the icon set. Every shadow is tinted warm because plain black shadows on cream look like stickers. The corners got a bit rounder and the controls became pills. The whole thing is set in Fredoka, a rounded display face that weighs about 30kB which I thought fit perfectly with the cute little mascot.

Here are a few before and after shots of the main content pages, with a bonus shot of the new pill navigation that smaller screens finally got:

The data enrichments will continue until “Morella” improves.#

Get it? No? Ok, I’ll see myself out.

The database had severity ratings for every plant, computed from symptom groupings and the old site displayed them precisely nowhere. Now, every card has a severity pill rated from Mild to Critical. The pills are also clickable filters on the main page’s plant cards. Search happens as you type and if you fumble the Latin a bit, a little Levenshtein pass offers “Did you mean Lilium?”. I thought this was a little bit more helpful than what the old site did after literally joking about spelling mistakes in its empty state.

A few other mentionable updates:

• A safe plants list, because the site only ever told you what not to buy. Every entry has to clear the ASPCA non-toxic list and be absent from my own toxic database before it’s allowed in.
• A symptom finder that allows you to perform a plant search backwards. You can click on multiple symptoms and it’ll filter accordingly.
• An emergency strip on every plant page with the poison-control hotlines. Unfortunately, for now, these are US numbers. Localising them by region is on the roadmap.
• Wikipedia descriptions for nearly every plant credited under CC BY-SA.
• Around 3,000 common-name redirects, so /plant/peace-lily/ finally lands somewhere useful.
• Because it made sense, the whole thing is now a PWA and works completely offline. So, now you can use the site in a greenhouse with no signal, which is precisely where this site is most likely to get used.

Once I started auditing the data properly, I started to see a few additional gaps. There were several plants with multiple entries under different, but similar, names. I deduped and merged the symptom data and also updated the severity groupings to make more sense.

I also quickly realised that merging seizure into seizures would have silently promoted over a hundred plants to “Critical”. The severity groups treated those two spellings as different levels. The little cleaner script I threw together caught it during a dry run. The script grew a rule about never merging across severity levels as a result. The plants that genuinely deserved promotion got one. For instance white snakeroot, the plant that killed Lincoln’s mother, was somehow rated “Severe”. The script properly re-rated it to “Critical”.

The enrichment didn’t stop there. I sourced proper taxonomy for every record via GBIF, per-plant toxicity principles with a glossary and little world maps showing their native origins.

There was also quite a bit of fat to trim.#

Somewhere in all this I noticed every page weighed over 200kB. This included pages that were basically just copy. The culprits were painfully self-inflicted. There was an 85kB inline script shipping all ten animated logo SVGs to every single page. The same animal icon inlined seventy times on the front page. Oh, and let’s not forget my personal favourite, the attributions page carrying 149kB of pure indentation that a template loop had quietly emitted. I was shipping whitespace at scale.

The fixes were old-school and very satisfying. A single fingerprinted and cached JS bundle, SVG sprites so each drawing only ships once and one well-placed whitespace trim yielded the following results:

No framework was harmed, or indeed present, in the making of this facelift.

We ship from the homelab now.#

The last box to tick from the original post was the bittersweet one. In 2022 I wanted the project “open-source and community-driven” on GitHub. In practice, the community contribution was me, at midnight, fixing my own typos. So, the repository followed this blog into my homelab using the exact same moving parts as outlined in My Blog Now Ships From My Homelab!. It just made sense after this site’s migration. The data remains as open as ever through the API, which was always the part worth opening. That will never change.

While migrating I had a small panic about the 315MB of plant photos sitting in my working tree, imagining every CI build hauling them across the network. Turns out my 2023 self had already gitignored them and the entire repository clones at 7.5MB. Every once in a blue moon past me does something right. I’ve decided to let sleeping dogs lie and not investigate what else he buried in there.

Was the juice worth the squeeze?#

Very much so. The site is faster, cuter and finally says the most important thing it knows on every card: how dangerous is this plant, not just whether. It builds from nothing with a single binary and deploys itself when I push. The data is cleaner and more robust than it has ever been and enriched well past what 2022 me had the patience for.

But the honest win is the same one as the blog demolition. The whole thing is now boring to operate and boring is what lets a hobby project survive its maintainer’s attention span.

If you have a plant-curious pet, Plant🌱Smart is free, the API is free and the safe list might even let you buy something nice for yourself. And if four years from now there’s a third post in this series, may it be shorter than this one.

Anyways, adios…

So, having been bitten several times by intermittent outages and service disruptions, I figured a small personal win would be to migrate the repository for this site to the homelab. Now, it lives on my own Forgejo forge and the builds run on my own Woodpecker cluster. The only things that leave the network are static build artefacts that get pushed up to Cloudflare Pages.

The switch was surprisingly straightforward and took less than 30 minutes overall.

Before anyone reaches for the comment box, no, you don’t need a homelab for any of this. Forgejo and a Woodpecker cluster ( server and at least one agent ) will happily run on a spare mini PC, an old laptop, that Raspberry Pi you bought with the best of intentions or even as a single Docker Compose file running on the machine you use every day.

How complex can this possibly be?#

The first useful thing I did was ask myself what GitHub was actually doing for me when it comes to managing this site. After some mulling about, I could only really list the following:

• Hosting a git repository.
• Hosting the comment threads, via giscus Discussions.

That’s pretty much it. I don’t use Actions and GitHub alone never built this site. Cloudflare Pages watched the main branch and did the building itself. This is something I covered back in My Blog Publishing Setup. GitHub’s one job was holding a bunch of markdown files.

That’s a strange thing to accept as a single point of failure.

The new shape of things.#

The replacement looks like this:

• I push to Forgejo, which lives inside my homelab network.
• Forgejo fires off a message to the Woodpecker Server over a webhook. Also inside the network.
• The Woodpecker Server assigns the job to an available Woodpecker Agent, which clones the repo, builds the site with Hugo and pushes the result to Cloudflare Pages with wrangler.
• Cloudflare serves the files at the edge, exactly as before.

I just added support for mermaid diagrams, so of course I’m not going to let the opportunity to show it off slide:

The part I want you to notice is the direction of travel. Under the old setup, Cloudflare reached into GitHub to pull my source. Under the new one, nothing reaches in at all. The forge and the CI server accept no traffic from the internet. The only packet that crosses the network boundary is an outbound upload of compiled static assets.

That reversal is the entire security model which was pretty much the point. What looks like “the old way but more steps” allows me to control every aspect of the pipeline up to just before we ship the build artefacts. A push-based deploy means self-hosting your forge requires exposing exactly nothing. No reverse proxy gymnastics, no VPN for the webhook and no port forwarding required.

If my homelab bursts into flames mid-afternoon ( a real possibility as I do live in Queensland, Australia ) Cloudflare keeps serving the last deploy and nobody visiting the site would ever know. That being said, nobody actually does visit this site, so…

A small intermission.#

A short aside, because it’s a question I’d ask. My internal services hang off a domain I genuinely own, but resolving it depends on where you’re standing. Inside the network a locally hosted 3-node Technitium cluster runs the hosted zone and the router sends all DNS requests through it. Initially, I used this for network-wide adblock, which works an absolute treat. It also means the forge and the CI cluster resolve to their internal addresses. Outside the network, the public zone points at a landing page hosted elsewhere.

Same hostname and two completely different worlds depending on which side of the wall you’re on. Split-horizon DNS is nothing new, but it’s what lets me use real TLS-friendly hostnames for internal services without those services ever being reachable from the internet.

If I did decide to open some services to the outside world, like my Navidrome server, I could use an overlay network like Netbird to provide friends and family access via a familiar naming convention without ever opening a port on the router.

The part Cloudflare doesn’t clearly advertise.#

A Pages project is either connected to a git provider or it accepts direct uploads. Never both. As long as your project is wired to GitHub, wrangler pages deploy will be rejected and you will get screamed at.

Disconnect the git integration in the project settings and the project quietly converts to “Direct Upload” mode. It keeps its name, its custom domain and its whole deployment history. It just stops watching a repository and starts waiting for you to hand it those delicious files. While you’re in there, make sure the production branch is properly specified: main in my case. This matters because Wrangler tags each upload with a branch name. An upload whose branch matches the production branch goes live on the site. An upload under any other name becomes a preview deployment with its own URL instead.

After that, the deploy is one command requiring two secrets:

• An API token scoped to Cloudflare Pages: Edit
• Your Cloudflare account ID.

Both go into the Woodpecker Server as repository secrets.

Finally, our favourite! YAML.#

The whole thing is just one file named .woodpecker.yml that squats in the repository root.

when:
  - event: [push, manual]
    branch: main

clone:
  git:
    image: woodpeckerci/plugin-git
    settings:
      partial: false
      tags: true

steps:
  diagrams:
    image: minlag/mermaid-cli:11.16.1
    commands:
      - ./bin/render-diagrams

  build:
    image: hugomods/hugo:debian-git-0.163.3
    environment:
      HUGO_ENV: production
      HUGO_ENVIRONMENT: production
    commands:
      - git config --global --add safe.directory '*'
      - ./bin/changelog
      - hugo --gc

  deploy:
    image: node:22-slim
    environment:
      CLOUDFLARE_API_TOKEN:
        from_secret: cloudflare_api_token
      CLOUDFLARE_ACCOUNT_ID:
        from_secret: cloudflare_account_id
    commands:
      - >-
        npx --yes wrangler@4 pages deploy public
        --project-name=wilhelm-codes
        --branch=main
        --commit-hash="${CI_COMMIT_SHA}"
    when:
      - event: push

Only build off main.#

I test design changes and new entries locally, so a push to any other branch doesn’t start a pipeline.

We want a full clone, not a shallow one.#

This site’s changelog page renders the git log and Hugo’s enableGitInfo reads commit dates for every page. This is something I wrote about in A Changelog That Builds Itself. CI systems love shallow clones and a shallow clone here means I can’t convey the full historical picture on the page. Worse, enableGitInfo derives every article’s dates from that same truncated log, so they all come out wrong besides. Setting partial: false makes Woodpecker fetch the entire history.

Diagrams render before anything else.#

Articles on this site can embed Mermaid diagrams, like the sequence diagram further up the page. They render to static SVG at build time, not in your browser, so the site ships zero diagram JavaScript. A small script hashes each diagram’s source, renders anything that has no matching SVG yet and prunes any SVG nothing references any more. I run it locally and commit the SVGs alongside the content, which means on a clean commit this step does precisely nothing. It exists as a safety net for the day I inevitably forget.

So when I said the diagram was rendered by the pipeline it describes, I meant it literally. If I ever edit that diagram and forget to render it, this step is what quietly saves the deploy.

The build step is a stock Hugo image.#

Nothing is installed on the agent itself unless you count Docker image pulls. The image pins the exact Hugo version, ships the extended edition and includes git and bash. Both of which the changelog script that generates the data requires. The safe.directory line exists because the cloned workspace is owned by a different user than the one inside the container and git these days refuses to read a repository it thinks you stole.

The deploy step is a stock Node image.#

npx pulls Wrangler at run time. Wrangler then reads the two secrets from the environment and pushes public/ up to Pages and that’s pretty much it. Dependencies are snagged and cached at build time, which means nothing to maintain on the agents. Either step’s version gets bumped by editing one line.

Complete parity with what Cloudflare’s own build pipeline was doing, except now I can read every line of it and make it do whatever I need.

I did run into some speed bumps along the way.#

For the record, it took only three tries to get the pipeline to a “green” state.

In order of discovery:

• The plain version tags of the Hugo image are the extended edition. The reg- prefix means regular and none of them include git unless the tag says git. The tag you guess first ( exts-<version> ) doesn’t exist. It’s an odd convention, which is why it threw me off.
• Woodpecker substitutes ${VAR} expressions in the YAML before the shell ever runs. Anything it doesn’t know becomes an empty string. My safe.directory "${CI_WORKSPACE}" quietly became safe.directory "". Hence the asterisk / glob in the YAML.
• The changelog script opens with #!/usr/bin/env bash and the default Hugo images are Alpine. env: can't execute 'bash' is the whole error message you get, so I just went with the Debian variants instead which include bash out of the box.

None of these are hard problems, but worth pointing out.

I’m not deleting the old repository… completely.#

The GitHub repository still exists if only to provide a place for the giscus integration to store comments. It offloads most of this functionality to GitHub’s Discussions feature. Delete the repo and every comment ever left on this site goes with it; all 2 of them.

It no longer needed the full source history to do that job either. It was ported on over to my local forge with Forgejo’s native GitHub repository migration feature. So, I force-pushed the whole history into a black hole, leaving a single commit containing only a README. The remaining husk also has a second job coming; it’ll eventually host the companion code for tutorial content, so readers can clone examples without ever touching my forge.

Each service kept exactly the job it’s uniquely good at. Cloudflare serves files from the edge better than my house ever could and no fucking way am I publicly opening ports on a router. I’d rather lick the rim of a pub toilet. GitHub Discussions gives commenters an identity they already have. Everything else now lives at home.

In closing …#

Was any of this necessary? For a static blog that deploys in under a minute, probably not. The old setup worked fine and if yours does too, keep it. I’m not here to convince anyone.

There’s a special kind of satisfaction in watching a pipeline run end to end on hardware you can physically point at, knowing the only cloud dependency left is the one actually earning its keep. The next GitHub outage can happen without me. At least for this project anyway.

So, of course just weeks later I have this burning desire to nuke it all from orbit!

To be clear, the June cleanup wasn’t wrong. The pipeline was genuinely tidy. But, a tidy pipeline is still a pipeline and somewhere between then and now I started asking a more annoying question: why does a personal blog, a pile of static text, need a JavaScript toolchain at all? Why do I need to buy into the Tailwind framework when I knew full well how to write vanilla CSS with my own hands? Every npm install was a little tax that I’d eventually have to pay with interest the next time I wanted to update the site’s dependencies. I felt as if I wasn’t maintaining a blog. I was maintaining the machinery that produces a blog and the machinery had some very strong opinions.

So, I did a hard reset with a very satisfying amount of deleting.

The demolition …#

Here’s the bill for the redesign commit:

230 files changed, 3951 insertions(+), 33365 deletions(-)

That’s roughly a 10-to-1 ratio of deleted to written. Which, as a software engineer, is my favourite kind of ratio. I happily added the following the to chopping block:

• Tailwind v4 and the typography plugin. Replaced by one hand-written CSS file. The whole thing gzips to under ~10kB with syntax highlighting included.
• The entire Node toolchain. The package.json, lockfile, Prettier and its plugins. There is no npm install step anymore because there is no npm anymore.
• Fuse.js and the ⌘K search palette. Nobody was searching this blog. I checked. It was me. I was nobody.
• Two self-hosted webfonts. More on this in a second, because it’s the biggest single win.
• The changelog page. This pulled from the GitHub events API and shipped with an 18,016-line JSON fixture for local dev. Eighteen thousand lines of someone else’s API response, committed to my repo. So, a page barely anybody visited could render in development. I mean, I added it back becase I missed it, but it’s much more efficient now.
• 68 of the 79 icon SVGs. A 390-line drawer menu and a taxonomy I’d stopped using.

The layouts went from 2,868 lines of template across 48 files to about 800 lines across 21. Not because I got cleverer, but because most of that code was written for the joy of it. Which, look, is a fine reason to build something. It’s just a bad reason to keep serving it to strangers. And with all that complexity and cruft came what felt like a lot of brittleness.

The fonts had to go too.#

This one hurt a little. I like Inter and Rubik. Together they were 449kB of woff2 riding along on every first visit. Which made them, by an enormous margin, the heaviest thing on the site.

So, I dropped them and switched to the system font stack which, to my surprise, actually looked better on the site. The actual typeface was doing very little. Your operating system already ships a perfectly good set. All lovingly hinted by people with far more patience and experience than myself. Best of all it costs zero bytes to use!

Hugo, finally home alone.#

Thanks to all the trimmed fat, the build process is effectively just hugo. No more extended binary, SCSS, image processing or defining NODE_VERSION in Cloudflare Pages required. Fewer dependencies mean fewer moving parts and that’s always an improvement.

Numbers, or it didn’t happen.#

Right after the deploy I proudly measured the new site and announced it was “under 100kB”. Which would have been true if the production site were served by my dev server, uncompressed, with a 40kB livereload script attached. I made the mistake of measuring the network stats on my local development server. Womp, womp.

The real numbers, from the live site with Cloudflare’s brotli doing its thing:

The single largest asset on the home page is now the favicon. 7.5kB; roughly a third of the total weight. I think you’re allowed to stop optimising when your largest single asset is your favicon.ico. It’s an image of my gorgeous mug. It stays. I’m quite attached to it.

An ambitious first pass.#

In retrospect, I wanted to make everything simpler and unintentionally over-compensated in the opposite direction. I stripped out too much and was now staring at a sad little blog with zero personality.

So, the second half of the job was building the personality back and making my selections a bit more deliberate. One thing led to another and I think I’ve produced my finest work yet on a personal blog. It’s small and lightening fast. I’m not sure where else I can optimise without drastically affecting the overall vibe of the design; the law of diminishing returns… returns.

The thing about now having such a light frame is adding to it stops feeling like a burden, or something future Wilhelm will have to pay. For example, here are the biggest things I’ve added and they barely increased the overall “weight” of the design.

Series#

A proper taxonomy for multi-part writing. Built because I’ve been wanting to write a Cyberpunk-themed set of tutorials for writing advanced HCL in Go. The series will be about eight posts long and outside of sharing a tag, I had no way to string them together. Series posts wear a stacked-sheet card, a segmented progress meter that is absolutely not a cyberdeck RAM readout and a panel showing every part in the run, including the ones that don’t exist yet.

The unpublished parts of a series ship as glyph noise and decode, left to right, when you point at them. The real titles sit in aria-label the whole time, so a screen reader is never handed the static. The browser tab pulls the same trick on every page load, because a title bar is just a very small marquee nobody was using.

Try moving your mouse pointer over some of the “encrypted” titles on the new dedicated page.

Tired LEDs#

The lit chips in the series meters, static leaders in the main page’s hero section and a scattered handful of cells in the activity graph flicker like hardware that has seen some things. Their animation clocks share no common factors, so the pattern never visibly repeats. The same no-RNG randomness as the heading glitch. On page load the whole graph boots like an old panel, dark, then a sputter per cell, then steady stream of blinking boxes. Reminiscent of the old monochrome screens and beige boxes of my youth.

Christ, I’m getting old.

Changelog, resurrected#

Yes, the one from the butcher’s block above. However, instead of hitting the associated Github repository directly at build time using a PAT, the new one doesn’t call anyone. Commit data is sourced directly from Cloudflare Pages’ shallow clone it checks out during build time. There’s a simple 20-or-so-line shell script reads git log and Hugo renders the result. HEAD gets a lit node that flickers, because why the hell not?

Image shortcodes#

Something I’ve been meaning to add is support for various ways to display images. Each image can now be clicked-to-zoom with attribution in the following forms:

• Masonry.
• A scrollable, horizontal display.
• Last, but not least, the typicla single image display.

There’s actually a sneaky, super-secret page I use to test all my shortcodes and typography stylings where you can see everything for yourself.

Even with all these complex additions, it all adds up to a few kilobytes of CSS and inline script. Which is to say the entire second wave of features weighs an order of magnitude less than one of the webfonts I deleted.

My new favourite fidget toy.#

The part I didn’t expect was to glue my eyeballs to the Firefox throttle menu under its network tools panel.

I flipped it to a 2G profile just for shits and giggles - call it a generous 50kb per second - and did the napkin math. The old site’s 750kB works out to between 60 to 90 seconds of staring at a blank viewport. The new site lands in about four seconds on a connection profile most of the industry stopped thinking about a decade ago.

I have reloaded this page on simulated garbage networks far more times than any reasonable person should, and it is satisfying every single time. The page just… appears. Like a website. Remember plain’ole websites?

None of this is novel, I know. The “your blog doesn’t need 2MB of JavaScript” essay has been written a hundred times. Usually on a blog serving 2MB of JavaScript. I’m not even the hundred-and-first person to do this. But, there’s a difference between nodding along to the idea and watching your own site load over a simulated tin-can connection before you can finish blinking.

In closing …#

The funny thing about the June post is that it ended with me feeling like the blog was finally sorted. And it was! For the architecture it had. It just turned out the architecture itself was the thing that needed to go.

The site is now boring in the best possible way. It builds with one command, it has no dependencies to rot behind my back and the whole design fits in one stylesheet I can actually hold in my head ( not really ). Fewer moving parts, fewer things to forget, fewer surprises the next time I touch it in six months. Best of all, it looks fucking great!

Set-and-forget, but this time with almost nothing left to forget. … Right?

I also can’t decide on which activity graph animation I like the most. 😅

So let me finally show you my bits.

What even is a bit?#

A bit is the smallest unit of “I made a thing” I’m willing to commit to. It could be a quote that stuck with me, a link worth keeping, the odd YouTube video, or a one-line thought too small to earn its own long-form entry. Each one is a little markdown file in /bits and the only thing it really has to declare is what kind of bit it is:

---
type: quote
date: 2026-06-17
source: "Edsger Dijkstra"
---
"Simplicity is a great virtue but it requires hard work to achieve it."

type is the whole trick that everything else hangs off.

One shape per thought.#

The thing I didn’t want was for a pithy quote to render like a bare link or to render like a video. They’re different shapes of thought, so they ought to look different.

I’d already learned this lesson building the changelog, which leans on one tiny partial per event type. So I stole from myself. There’s a single lookup table mapping each type to an icon, an accent colour and a label:

{{ $meta := dict
  "quote" (dict "icon" "quote-right"    "colour" "rose"    "label" "quote")
  "link"  (dict "icon" "arrow-up-right" "colour" "blue"    "label" "link")
  "video" (dict "icon" "youtube"        "colour" "red"     "label" "video")
  "blurb" (dict "icon" "pen-nib"        "colour" "emerald" "label" "blurb")
}}

It then matches a micro-partial per type that decides how the content actually renders. Adding a brand new kind of bit is now “add one row, add one tiny template”, which is about as many steps as I’m willing to tolerate.

Hugo, why are you like this?#

My bits started life with two perfectly reasonable front-matter fields: type and url. Hugo took one look and quietly robbed me of both.

It turns out url is a reserved key which Hugo uses to treat as the page’s permalink. So, the moment I put a https://... in there, the build fell over with a stern little message about unsupported protocols. type doesn’t even have the decency to error. It silently moves out of .Params.type and into .Type, which also hijacks the layout lookup. So my .Params.type was resolving to nothing and every single bit was quietly rendering as the fallback.

Turns out hte fix for this was simply to rename url to link and read .Type instead of .Params.type. Half an hour of my life dedicated to two words I didn’t know were already spoken for.

Coding is my passion.

Bits flapping in the wind.#

Rather than dumping bits into the same fold-out list as the GitHub noise, I pulled them out as their own first-class timeline rows. The lower-signal changelog chatter stays tucked behind the “N changelog events in between” disclosure. So, the home page now reads in three tiers:

• the loud headline articles
• the medium-volume bits
• the quiet changelog hum

The same interstitial machinery I built last time, but bits just get to stand a little taller than a commit.

The tag that went nowhere.#

Bits are deliberately render: never in Hugo. They live inline on the bits page and never get their own URL. Except “no page” also quietly means “no place in the taxonomy”, which means a tag only ever used by a bit has no /tags/... page to point at. If I link it anyway I’ve shipped a 404.

So, the tags only become links if there’s actually somewhere to go:

{{ with site.GetPage (printf "/tags/%s" (urlize .)) }}
  <a href="{{ .RelPermalink }}">#{{ .Data.Term }}</a>
{{ else }}
  <span>#{{ . }}</span>
{{ end }}

A tag with a real page becomes a link and a bit-only tag stays as plain text. No broken links and the nice part is it heals itself the moment a proper article picks up the same tag.

In closing …#

The front page has quietly turned into a proper little stream. Long-form when I’ve actually got something to say, bits when I don’t and a year of squircles up top keeping a tally of it all.

Which is the entire point. The less effort it takes to post a half-formed thought, the more likely I am to actually post it. And the more I post, the more those gaps fill in.

And, as always, you can check everything out for yourself in the repo.

I want to fill those gaps in and not with more full-fat rows, but with a small line between each pair of articles. Something like “1 bit and 41 changelog events in between”; a kind of interstitial event timeline for all the work that never quite became a full blog post.

Why can’t I hold all these events?#

The trick to merging things that don’t look alike… You’re never going to believe this… is to make them look alike. I already pull my GitHub activity for the changelog, or, at least, the last 100 or so events. So, I reused that, threw the bits in alongside it, and normalised the whole lot into one boring, uniform shape. This data structure doesn’t hold all the data for each event, but just enough to cover the highlights.

{{ $events = $events | append (dict
  "kind"  "commit"
  "date"  (time.AsTime .commit.author.date)
  "title" (index (split .commit.message "\n") 0)
  "url"   .html_url
  "icon"  "code-commit"
  "colour" "green"
  "data"  .)
}}

Every piece of content on this site has at the very last these attributes. So created a unifying model is pretty straight-forward. A kind, a date, a title, a link, and enough leftover metadata to do something creative with later if I feel like it. I made a point of keeping the original object tucked away in data too; a gift to future Wilhelm.

Minding the gaps.#

With one big sorted pile of events, the rest is just bookkeeping. Walk the articles newest to oldest, and for each one work out the window between it and the article above it. Then, scoop up every event that falls within the relevant dates:

{{ $upper := $now }}
{{ if gt $i 0 }}{{ $upper = (index $articles (sub $i 1)).Date }}{{ end }}
{{ range $e := $events }}
  {{ if and ($e.date.After $article.Date) (not ($e.date.After $upper)) }}
    {{ $group = $group | append $e }}
  {{ end }}
{{ end }}

The newest article’s “window” runs all the way up to now, so whatever I’ve been doing since the last post shows up at the very top. If there’s an empty gap the event list doesn’t render.

Listing the interstitial events.#

A summary is nice, but I wanted to be able to actually see the events without leaving the page. Normally that’s where a pile of JS shows up. But, just as with the activity graph, we’re going to rely on pure HTML and CSS. The <details> element does the entire job for free:

<details class="group">
  <summary>... 41 changelog events in between ...</summary>
  <ul>
    <!-- one little row per event, complete with icon and link -->
  </ul>
</details>

Click the summary, the gap unfolds into a tidy little list of every commit, PR and bit. Each linked off to wherever it lives. The default disclosure triangle gets binned and replaced with a chevron that flips on open, courtesy of Tailwind’s group-open: variant. Still no JS and I’ll remain quietly smug about that.

Saving myself a small headache.#

Finally, there’s the the responsive question. This site’s overall design isn’t exactly “mobile first” and viewing it on a small screen strips away a lot of detail already. All these thin dividers and fold-out lists look great on a wide screen and turn into a cramped mess on a phone.

I thought about it for a while and weighed up some clever reflowing. In the end I did the only sensible thing and hid the whole timeline below the sm breakpoint. On a phone you get the clean list of articles, but on a desktop you get the full story between them.

That being said, I do need to return and focus on making the mobile experience a bit more palatable.

In closing …#

What I like about this is that it turns my worst blogging habit - vanishing for months and then resurfacing in a manic flurry - into something the site can actually narrate. The big rows are the headlines while the quiet lines between them are everything else.

It’s also wired up so I can grow it later without unpicking anything. Right now it’s counts and lists, but tomorrow it could filters, more details, or do something I haven’t thought of yet. All off the same pile of events.

For now, though, the gaps have something interesting in them. Which is a much nicer thing to scroll past than a year of silence.

I wanted something that summed up “Has Wilhelm actually been doing anything lately?” at a glance, without the density of 365 tiny day cells. Fifty-two squircles felt about right. Coarse enough to read across the room, fine enough to still give a picture.

What counts as a “week’s worth of activity”?#

The short answer is everything. The changelog already pulls my GitHub activity at build time, so I reuse that exact same data. Then, I throw in the things GitHub doesn’t know about; every type of blog post on this site.

Because the changelog fetching already lives in a tidy little partial, sourcing the everything is just a matter of asking for each one and collecting all the publish dates:

{{ $dates := slice }}
{{ range partial "changelog/fetch.html" (dict "url" $commitsUrl "fixture" $fixture) }}
  {{ $dates = $dates | append (time.AsTime .commit.author.date) }}
{{ end }}
{{ range where site.RegularPages "Section" "blog" }}
  {{ $dates = $dates | append .Date }}
{{ end }}

Nothing crazy going on here. I’m just creating a big list of timestamps from wherever I happen to leave a trail.

Sorting a pile of dates into weekly buckets.#

Each of these dates now need to land in one of fifty-two buckets. Working out which week a given date belongs to is just some boring epoch arithmetic; how many whole weeks ago was it?

{{ $ago := int (div (sub now.Unix $d.Unix) 604800) }}
{{ if and (ge $ago 0) (lt $ago 52) }}
  {{ $counts.Add (printf "%d" (sub 51 $ago)) 1 }}
{{ end }}

That 604800 is the number of seconds in a week. And yes, I did have to look that up. Anything older than fifty-two weeks just falls off the back and is quietly ignored.

Painting the squircles.#

My favourite part of this is there’s no JS involved. The whole thing is a CSS grid of twenty-six columns, and because each squircle is aspect-square, the rows just work and the squircles stretch to fill whatever container I drop the partial into:

<div class="grid grid-cols-26 gap-1.5">
  <!-- 52 of these green little dudes -->
  <div class="aspect-square rounded-full bg-emerald-400"></div>
</div>

Working out the shade was the fiddly bit. My first attempt simply scaled each week against the busiest one, which sounds sensible right up until you remember my data is basically one enormous week and a whole lot of flat nothing. That single monster week hogged the dark end and squashed everything else into the same pale green. So I did what GitHub does and reached for quartiles instead. You rank the weeks that actually saw some activity, chop them into four groups, and let a week’s colour come from where it lands in the pack rather than from some absolute number. Empty weeks stay a faint emerald-100; the rest climb through four steps of green up to emerald-600. The part I like is that it’s relative to me; a busy week is only busy compared to my other weeks.

The little tooltip that pops up when you hover over a squircle is also pure CSS. A group on the wrapper, a group-hover:opacity-100 on the popup, a transition is all I needed. Each squircle now gives a little scale on hover too, just because it’s nice.

The graph’s painful honesty.#

Now on to the more embarrassing part. When I first rendered it with real data, I got one lonely green squircle and fifty-one empty ones. Surely, you’ve noticed it on the front page.

For the curious, this is what it would look like if I didn’t have commitment issues.

At the time I assumed I’d done something wrong. But, to my great shame, I hadn’t. Turns out that when you vanish from your own website for close to 18 months and then cram an entire renovation into a single week, the graph renders exactly that. A long, flat, pale stretch of road ending with one pathetic little green emerald.

There’s an extra little indignity baked into the quartiles, too. They need a spread to rank against, and with exactly one active week there’s nothing to compare it to. So my massive renovation-cramming week doesn’t even get to be properly dark green. It turns up as a polite, middling shade.

I effectively built a little a tool whose entire job is to hold up a mirror to my own lack of consistency and commitment. Very cool! 😬👌

Drop it in anywhere.#

This whole thing is a single self-contained partial. It was waaaay easier to build out than I had originally thought. And, thanks to Tailwind I didn’t even have to fall back on any JS! I count that as a bonus.

For the moment, it’ll live on the home page, but I can now just place this anywhere in my Hugo site and it’ll work:

{{ partial "activity-graph.html" . }}

I might even build it out a bit more to support different colour schemes or specificy types of targeted site content. So, the more I write, the more those squircles fill in.

Consider yourself warned, me.

Confession Time#

While poking around the build, I discovered something a little embarrassing. My Tailwind setup - the source, the config, and the entire node_modules directory - was living inside Hugo’s static/ folder.

If you know Hugo, you already know where this is going. Everything in static/ gets copied, verbatim, into the final site. Which means I had been cheerfully publishing my whole build toolchain - megabytes of it - to the live site on every single deploy. So, yeah. Production was shipping node_modules. Coding is my passion.

Nobody noticed, nothing broke, and the world kept turning. But it’s the kind of thing that, once you see it, you can’t un-see. To be fair to myself, when I originally put this Hugo site together, I only learned enough to get something shipped.

Letting Hugo do the heavy lifting.#

The reason that mess existed in the first place was that I’d wired up Tailwind as a separate, manual build step that spat out a compiled stylesheet for Hugo to pick up. It worked, but it was a second moving part I had to remember existed.

The good news is that recent versions of Hugo can drive Tailwind itself, natively, as part of the normal asset pipeline. Combined with Tailwind v4 - which finally ditches the JavaScript config file in favour of configuring everything in CSS - I got to delete a lot of stuff:

$ git diff --shortstat main...modernize
64 files changed, 1872 insertions(+), 40197 deletions(-)

The whole stylesheet now starts its life as a single entry point:

@import "tailwindcss";
@plugin "@tailwindcss/typography";
@source "hugo_stats.json";

That hugo_stats.json bit is the clever part. Hugo writes out a list of every utility class it actually emits, and Tailwind reads that to decide what to generate. No more pointing Tailwind at my templates and hoping it guesses right.

Then a small partial hands it all off to Hugo to compile, minify and fingerprint:

{{- with (templates.Defer (dict "key" "css")) }}
  {{- with resources.Get "css/main.css" }}
    {{- $opts := dict "minify" (not hugo.IsDevelopment) }}
    {{- with . | css.TailwindCSS $opts }}
      {{- /* ...do very cool things... */ -}}
    {{- end }}
  {{- end }}
{{- end }}

The templates.Defer wrapper is there because the CSS can’t compiled ( transpiled? ) until Hugo has finished rendering every page and knows the full list of classes. So, in a very real way, Hugo solves an annoying 🐔 and 🥚 problem.

This means no more standalone Tailwind config, no committed stylesheet, no node_modules in static/, and no build toolchain leaking onto the live site. Very cool!

So. Many. Deprecations.#

Of course, nothing that’s been left alone for a year comes back to life cleanly. Bumping Hugo to the latest release lit up the console like a Christmas tree.

A few of my templates were leaning on things that have since been politely shown the door:

• resources.GetRemote ... .Err for the changelog page - that pattern was removed in favour of a shiny new try keyword.
• .Language.LanguageCode and .Language.LanguageDirection, both deprecated in favour of .Locale and .Direction.
• The _build and cascade._target front matter keys, now just build and cascade.target.

None of it was hard to fix, but it’s a good reminder that “it still builds” and “it builds without complaints” are two very different bars.

A Footgun!#

Here’s a fun one. The changelog page pulls in a Github event fixture file during local development by fetching it over http://localhost:1313. Effectively, from the very dev server that’s trying to build the page.

Those of you who are familiar with such things can probably see the problem. Hugo builds the site before it starts listening on that port, so the build sits there waiting for a server that doesn’t exist yet. A deadlock of my own making. The obvious fix was to just read the file off disk instead of asking the network nicely.

Some honourable mentions.#

A grab-bag of smaller wins while I had the hood up:

• Fonts are now served as woff2 instead of raw ttf, with font-display: swap so text shows up immediately instead of hanging around invisible. This alone shaved the font payload down by about 60%.
• I also deleted a few MB of fluff that wasn’t being loaded by anything.
• Prettier got a nice version bump and I taught it to sort my Tailwind classes, so I can stop pretending I do that consistently by hand.

Was the juice worth the squeeze?#

Aside from a few cosmetic updates here and there, the site should look pretty much the same as it did before. Which is, weirdly, the whole point; all of this work was about the parts you can’t see. I got a leaner build, faster page loads, and a project I can come back to in another year without wincing; famous last words, etc…

For now, the house is clean. Very nice.

If you use Github, you know it quietly records nearly everything you do as a stream of events. Better still, for a public repository, that stream is available over a public, unauthenticated API endpoint through a simple GET request.

So the plan more or less writes itself. We fetch the stream at build time, group the events by day, and let Hugo render them. Hugo even has a tidy little function for pulling in remote resources that works like so:

{{ $url := "https://api.github.com/repos/wilhelm-murdoch/wilhelm.codes/events" }}
{{ with try (resources.GetRemote $url) }}
  {{ $events := .Value | transform.Unmarshal }}
  {{/* ...range over them and render... */}}
{{ end }}

Because this all happens at build time, the visitor never waits on GitHub. By the time the page reaches a browser it’s just static HTML like everything else. The changelog is always current as of the last deploy, and I never have to think about it.

That’s the part that worked. Now for the parts that didn’t.

… Then, production happened.#

I’ve been more or less absent from this site for close to a year, but this past week I’ve decided to breathe a bit more life into it. I made a few changes to modernise the stack, pushed my changes up and waited on Cloudflare to do its thing and…

ERROR error building site: ... error calling GetRemote:
failed to fetch remote resource from 'https://api.github.com/...': Forbidden

I was greeted with a 403. Except… I could paste that exact URL into my browser and get a perfectly happy wall of JSON back. So what gives?

Rate limiting, that’s what. GitHub’s unauthenticated API is capped at 60 requests per hour, per IP address. My build doesn’t run on my IP. It runs on a shared build machine alongside who-knows-how-many other people’s deploys, all of them hammering GitHub from the same handful of addresses. By the time my build rolled around, that bucket was bone dry.

Honestly, a 429 instead here would have saved me a bit of investigating, but I digress.

The solution was to created a properly scoped Github PAT. Using an authenticated request gets 5000 requests per hour, so I went about implementing support and handed it to the build as an environment variable, and taught the template to send it along:

{{ $opts := dict }}
{{ with os.Getenv "HUGO_GITHUB_TOKEN" }}
  {{ $opts = dict "headers" (dict "Authorization" (printf "Bearer %s" .)) }}
{{ end }}
{{ $remote := try (resources.GetRemote $url $opts) }}

It’s worth noting that Hugo won’t read just any environment variable. Its security policy only lets os.Getenv see variables prefixed with HUGO_. Name your token GITHUB_TOKEN and you’ll get a confusing fistful of nothing; name it HUGO_GITHUB_TOKEN and it works. Ask me how I know.

Hark! Another Footgun!#

With the token in place, the fetch succeeded and the build promptly fell over somewhere new:

error calling len: reflect: call of reflect.Value.Type on zero Value

This never showed up locally, which tells me I should do myself a favour and do a quick local production deployment as a preflight before I push to Github and trigger an automated build. Originally, in development I rendered the changelog from a single large fixture file stored locally on disk. This was before I implemented the PAT so I wouldn’t rate limit myself locally when testing. The live stream, however, contains event shapes my fixture simply didn’t. One of them was a push event carrying no commits at all, and my template did this without a second thought:

{{ if eq (len .payload.commits) 1 }}

Call len on something that exists and isn’t there and Go has a small panic about it. The fix is boring; stop assuming the field is there. Hugo’s with only enters the block when its argument is actually… something:

{{ with .payload.commits }}
  {{ if eq (len .) 1 }}
    {{/* the one-commit case */}}
  {{ else }}
    {{/* the many-commits case */}}
  {{ end }}
{{ end }}

Since I’ve implemented PAT support, I’m not so concerned about being rate-limited during local development, though I now use the fixtures as a fallback if any request fails. This allows me to keep working locally without disruption.

Don’t let someone else’s server break your build.#

The real personal lesson is the moment your build depends on a third party at build time, you’ve effectively ceded control of your deployment to them. GitHub rate-limits you, or has a wobble, or changes a payload shape, and suddenly your perfectly good site won’t deploy and you’ll have a hard time.

So the changelog no longer treats GitHub as load-bearing. If the fetch fails for any reason it shrugs, logs a warning, and falls back to that saved fixture instead of taking the whole deploy down with it:

{{ $remote := try (resources.GetRemote $url $opts) }}
{{ with $remote.Err }}
  {{ warnf "changelog: GitHub fetch failed (%s); using the fixture" . }}
  {{ $response = os.ReadFile "static/github.json" | transform.Unmarshal }}
{{ else with $remote.Value }}
  {{ $response = . | transform.Unmarshal }}
{{ end }}

The try keyword is the hero here as it catches the error that GetRemote would otherwise throw and hands it back to me as a value I can actually do something with, rather than a smoking crater where my build used to be. Worst case, the page shows slightly stale history. That’s a trade I’ll take every single time over a red deploy or disruption to my local flow.

In conclusion…#

Ironically, this is something I’ve dealt with quite frequently at work. Github & AWS API rate limits ( yes, we frequently got rate limited by the VPC API of all things ), Yarn will throw a 5xx and even Sentry will chimp out during source map uploads. All of these things can disrupt deployments.

The point is just assume these things will happen and then build defensively around them. I, ehhhh, just need to apply this wisdom to my personal stuff. 😅

Anyway, the changelog still builds itself. It just doesn’t get to take the rest of the site down with it anymore.

In this case, what I really needed was a simple way to assign an ordinal to an arbitrary number. For instance, if I have a value of 2, I might want to tack on a nd as a suffix, eg; 1st, 540th or 9001st and so on.

Specifically, I’d like to use this with dates, but from what I can tell, Hugo doesn’t support this out-of-the-box. Luckily, the framework gives you a few options to extend its functionality.

Shortcodes#

With shortcodes you can create snippets that act as functions which can be used to dynamically inject HTML – among other things – directly into your rendered markdown. You can even pass both named and positional arguments through the shortcode to modify their behaviour as needed.

For instance, I have this custom shortcode used for displaying styled block quotes like:

I also have this one that let’s me print out some fancy callouts:

Hugo ships with a default set of shortcodes covering a variety of additional kinds of embeddings.

Unfortunately, for my purposes, I’m not planning on using dynamic numeric ordinals in my markdown files. I need this to work with templates and for that, we use…

Partials#

Unlike shortcodes, partials are small re-usable HTML components that are typically used to keep code duplication down. They are effectively context-aware templates that can accept arbitrary data which can be used in generating desired output.

Here is a small example of how I use partials for this blog. It’s a small data card component you might find scattered throughout the site. Partials let you quickly change a UI component in one place while having it propagate everywhere else.

For the purpose of this article, they can also be used to create custom template “functions” like this which solves my very specific problem:

{{- if and ( eq ( mod . 10 ) 1 ) ( ne ( mod . 100 ) 11 ) -}}
    st
{{ else if and ( eq ( mod . 10 ) 2 ) ( ne ( mod . 100 ) 12 ) -}}
    nd
{{ else if and ( eq ( mod . 10 ) 3 ) ( ne ( mod . 100 ) 13 ) -}}
    rd
{{ else -}}
    th
{{ end -}}

This may look a bit unreadable to people who aren’t super-familiar with Hugo’s template syntax, but it effectively resolves to:

const number = 10
let ordinal = "th"
if (number % 10 == 1 && number % 100 != 11) {
	ordinal = "st"
} else if (number % 10 == 2 && number % 100 != 12) {
	ordinal = "nd"
} else if (number % 10 == 3 && number % 100 != 13) {
	ordinal = "rd"
}

console.log(number + ordinal)

// prints 10th

Anyways, I have this saved as partials/functions/ordinal.html and can reference this in any of my templates like so:

{{ partial "functions/ordinal.html" $number }}

Where $number is any arbitrary number I’d like an ordinal suffix for. Take the following example template which generates a random range of numbers and prints them out using my ordinal partial:

{{ range seq 10 }}
  {{.}}{{ partial "functions/ordinal.html" . }} 
{{ end }}

Which generates:

1st 2nd 3rd 4th 5th 6th 7th 8th 9th 10th

Ground-breaking work! I can finally use ordinals in dates. Not exactly something I expected to write an article about, but here we are. 🤷

First, a Small Rant#

Before you call me a Luddite, let’s be clear here, I don’t have an issue with the technology itself. I’m an engineer. I think it all has its uses, but force-feeding it into almost every aspect of our lives with no regard to any social and environmental impacts with frequently no chance of being able to easily opt-out does not sit right with me one bit.

We’ve seen this happen over the last decade with touchscreens, IoT, blockchain, NFTs, Web3 the list goes on. All promoted by the endless parade of interchangeable, nameless faceless talentless hacks and disingenuous grifters who only care about making “BIG LINE GO UP”.

It’s all so tiring, so perhaps you can understand why I’d immediately recoil in disgust and go my own way with an alternative I can control.

Or, to put it in even simpler terms:

The “Stack”#

I suppose it’s technically a “stack”, but it seems a bit funny to use the term when referencing a blog setup. Just as with my Plant🌱Smart project, the goal is to automate as much as possible while keeping maintenance requirements and hard- and soft-dollar costs as low as possible. For this, I need only use a handful of tools to keep this space operational.

As far as the question over “cost”, outside of time spent, it’s about ~$100 AUD per year for the domain name. This blog is a very small and inconsequential part of this domain, so the overall cost is absorbed by “other stuff”.

So, the greatest cost is… time? I guess 🤷

Obsidian#

While I won’t be going into what Obsidian is and how it works, I will say it’s been a personal boon in how I keep notes and track of ideas. I have a lot of fleeting / ephemeral thoughts I that would otherwise lose instantly if I didn’t immediately jot them down using this app.

So, it makes perfect sense for me to use my personal vault to store all my blog content. The fact Obsidian content nothing more than Markdown files makes working with them using other bits of tech that much easier.

Oh, it’s free btw.

Hugo#

This is probably one of the more popular options when it comes to static site generators. It’s easy to install, is incredibly extensible and has loads of documentation to help you along. The template syntax sits upon Golang’s templating engine, so if you have a strong background as a Go developer like myself, you’ll be right at home.

However, knowing Go isn’t a hard requirement though it will make getting on top of things quite a bit easier.

What I enjoyed while learning about this project was I got to control every aspect of how I wanted my blog to look and function. Building the current design from the ground up with Hugo was incredibly fun.

Also, free. Very cool.

Cloudflare#

I already used Cloudflare to manage this domain’s DNS settings, so it only made sense to publish my static site to Cloudflare Pages over, say, Vercel or Github Pages. There’s nothing spectacular going on here outside of me just wanting to keep these two things in the same place.

That being said, I have no issues with migrating else where if the need should ever arise. Though, I doubt this blog will hit the 20k file limit of Cloudflare Pages any time soon.

Again, free for the purposes of this article. If you don’t have a dedicated personal domain, you will be provided a subdomain attached to the pages.dev apex.

The Good Stuff#

How is this all put together for day-to-day usage? Luckily, the Cloudflare stuff runs on auto-pilot, so it’s pretty much set-and-forget. I suppose you could say the same about the other components, but they’re the parts I touch the most.

I have a single vault in Obsidian. It’s where all my thoughts go. Stored within is a top-level Blog/ directory. Care to hazard a guess as to what it may contain?

Hugo has the concept of page bundles where you can group all resources associated with your blog articles within a single directory. You’ll notice above all directories mirror the blog posts hosted on this site. In my case, we can consider the directory names to be the human-friendly slugs you see in your address bar that point to the associated content. Within these directories, you’d see any other resource I may link to; source code, images, etc… The best thing about this is I only have to perform a relative reference to these resources. If I want to link to image-1.png, I only have to reference it as ![](/blog/my-blog-publishing-setup/image-1.png) without worrying about specifying an absolute path; very nice.

When I want to write a new article, I first create a new directory here. I may already have the title of the article in mind, but it can be in flux until I decide to publish it. In the new directory, I create a file called index.md. This file contains all the content of the associated article written using Markdown.

I then use an Obsidian template dedicated to new blog posts and apply it to the new file. This ensures I have all front matter properties ready to go. This makes configuring my posts in the editor that much easier.

All that’s left is writing my articles! Well, not really. I need a way to synchronise these files with my local Hugo instance. As you can see here, the content mirrors what I have stored in my Obsidian vault.

This can be easily addressed with 2 small apps:

1. fswatch which monitors a specified directory for changes and allows you to trigger subsequent commands for specific file system events. Basically, I want to watch for any changes in my Obsidian vaults Blog/ directory.
2. rsync to dynamically keep the target Hugo directory in sync with the Obsidian source directory.

I, of course, have this placed in a script that I have running in the background while I write. This is a great help during the drafting phase as I have Hugo dynamically processing and displaying these changes locally. This allows me to easily proof my work visually as I carry on writing.

Here’s the full script:

#!/usr/bin/env bash

SOURCE=${SOURCE:="${1}"}
export SOURCE

DESTINATION=${DESTINATION:="${2}"}
export DESTINATION

fswatch -o "${SOURCE}" | while read -r event; do 
    rsync -av --delete "${SOURCE}" "${DESTINATION}";
done

I keep this running whenever I’m writing a new article. Obsidian saves in almost realtime, so as I type the changes almost immediately sync across to the local Hugo server so I can review my changes.

You effectively run it as:

$ ./sync.sh /path/to/obsidian/blog/ /path/to/hugo/content/

For rsync to work as intended and keep the destination directory completely in sync with the source directory, remember to add a trailing slash to both directory arguments.

No Auto-Commit?#

Nope. Not here. There are a few other peeps with blogs out there that “commit on change”, but I prefer to have a bit more control over what actually gets published. For that, I simply use plain-old git commands to publish my new article:

$ git add -A
$ git commit -m 'some banal new bullshit screed'
$ git push origin main

Cloudflare monitors the associated repository, picks up the change and the auto-magic-ally builds and pushes everything to the public eye.

With this flow, I can see my changes locally in near realtime and push to “production” only when I’m happy with the results.

In Closing …#

I’m stoked to have my very own place again that I have complete control over. I’ve thoroughly enjoyed creating this new blog design and I may even open-source it one day.

That said, I’ve made a very loose commitment to post a new article every week this year of our lord 2025 and I’m hoping this will make things heaps simpler. I only want to worry about what I’m going to write and just get the content out there.

I sincerely hope I can keep this self-imposed weekly commitment. 😬👍

Headings#

Sint sit cillum pariatur eiusmod nulla pariatur ipsum. Sit laborum anim qui mollit tempor pariatur nisi minim dolor. Aliquip et adipisicing sit sit fugiat commodo id sunt. Nostrud enim ad commodo incididunt cupidatat in ullamco ullamco Lorem cupidatat velit enim et Lorem. Ut laborum cillum laboris fugiat culpa sint irure do reprehenderit culpa occaecat. Exercitation esse mollit tempor magna aliqua in occaecat aliquip veniam reprehenderit nisi dolor in laboris dolore velit.

Heading two#

Aute officia nulla deserunt do deserunt cillum velit magna. Officia veniam culpa anim minim dolore labore pariatur voluptate id ad est duis quis velit dolor pariatur enim. Incididunt enim excepteur do veniam consequat culpa do voluptate dolor fugiat ad adipisicing sit. Labore officia est adipisicing dolore proident eiusmod exercitation deserunt ullamco anim do occaecat velit. Elit dolor consectetur proident sunt aliquip est do tempor quis aliqua culpa aute. Duis in tempor exercitation pariatur et adipisicing mollit irure tempor ut enim esse commodo laboris proident. Do excepteur laborum anim esse aliquip eu sit id Lorem incididunt elit irure ea nulla dolor et. Nulla amet fugiat qui minim deserunt enim eu cupidatat aute officia do velit ea reprehenderit.

Heading three#

Voluptate cupidatat cillum elit quis ipsum eu voluptate fugiat consectetur enim. Quis ut voluptate culpa ex anim aute consectetur dolore proident voluptate exercitation eiusmod. Esse in do anim magna minim culpa sint. Adipisicing ipsum consectetur proident ullamco magna sit amet aliqua aute fugiat laborum exercitation duis et.

Heading four#

Commodo fugiat aliqua minim quis pariatur mollit id tempor. Non occaecat minim esse enim aliqua adipisicing nostrud duis consequat eu adipisicing qui. Minim aliquip sit excepteur ipsum consequat laborum pariatur excepteur. Veniam fugiat et amet ad elit anim laborum duis mollit occaecat et et ipsum et reprehenderit. Occaecat aliquip dolore adipisicing sint labore occaecat officia fugiat. Quis adipisicing exercitation exercitation eu amet est laboris sunt nostrud ipsum reprehenderit ullamco. Enim sint ut consectetur id anim aute voluptate exercitation mollit dolore magna magna est Lorem. Ut adipisicing adipisicing aliqua ullamco voluptate labore nisi tempor esse magna incididunt.

Heading five#

Veniam enim esse amet veniam deserunt laboris amet enim consequat. Minim nostrud deserunt cillum consectetur commodo eu enim nostrud ullamco occaecat excepteur. Aliquip et ut est commodo enim dolor amet sint excepteur. Amet ad laboris laborum deserunt sint sunt aliqua commodo ex duis deserunt enim est ex labore ut. Duis incididunt velit adipisicing non incididunt adipisicing adipisicing. Ad irure duis nisi tempor eu dolor fugiat magna et consequat tempor eu ex dolore. Mollit esse nisi qui culpa ut nisi ex proident culpa cupidatat cillum culpa occaecat anim. Ut officia sit ea nisi ea excepteur nostrud ipsum et nulla.

Heading six#

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Paragraphs#

Incididunt ex adipisicing ea ullamco consectetur in voluptate proident fugiat tempor deserunt reprehenderit ullamco id dolore laborum. Do laboris laboris minim incididunt qui consectetur exercitation adipisicing dolore et magna consequat magna anim sunt. Officia fugiat Lorem sunt pariatur incididunt Lorem reprehenderit proident irure. Dolore ipsum aliqua mollit ad officia fugiat sit eu aliquip cupidatat ipsum duis laborum laborum fugiat esse. Voluptate anim ex dolore deserunt ea ex eiusmod irure. Occaecat excepteur aliqua exercitation aliquip dolor esse eu eu.

Officia dolore laborum aute incididunt commodo nisi velit est est elit et dolore elit exercitation. Enim aliquip magna id ipsum aliquip consectetur ad nulla quis. Incididunt pariatur dolor consectetur cillum enim velit cupidatat laborum quis ex.

Officia irure in non voluptate adipisicing sit amet tempor duis dolore deserunt enim ut. Reprehenderit incididunt in ad anim et deserunt deserunt Lorem laborum quis. Enim aute anim labore proident laboris voluptate elit excepteur in. Ex labore nulla velit officia ullamco Lorem Lorem id do. Dolore ullamco ipsum magna dolor pariatur voluptate ipsum id occaecat ipsum. Dolore tempor quis duis commodo quis quis enim.

Blockquotes#

Ad nisi laborum aute cupidatat magna deserunt eu id laboris id. Aliquip nulla cupidatat sint ex Lorem mollit laborum dolor amet est ut esse aute. Nostrud ex consequat id incididunt proident ipsum minim duis aliqua ut ex et ad quis. Laborum sint esse cillum anim nulla cillum consectetur aliqua sit. Nisi excepteur cillum labore amet excepteur commodo enim occaecat consequat ipsum proident exercitation duis id in.

Labore ea magna Lorem consequat aliquip consectetur cillum duis dolore. Et veniam dolor qui incididunt minim amet laboris sit. Dolore ad esse commodo et dolore amet est velit ut nisi ea. Excepteur ea nulla commodo dolore anim dolore adipisicing eiusmod labore id enim esse quis mollit deserunt est. Minim ea culpa voluptate nostrud commodo proident in duis aliquip minim.

Ipsum excepteur cupidatat sunt minim ad eiusmod tempor sit.

Adipisicing voluptate ipsum culpa voluptate id aute laboris labore esse fugiat veniam ullamco occaecat do ut. Tempor et esse reprehenderit veniam proident ipsum irure sit ullamco et labore ea excepteur nulla labore ut. Ex aute minim quis tempor in eu id id irure ea nostrud dolor esse.

Lists#

Ordered List#

1. Longan
2. Lychee
3. Excepteur ad cupidatat do elit laborum amet cillum reprehenderit consequat quis. Deserunt officia esse aliquip consectetur duis ut labore laborum commodo aliquip aliquip velit pariatur dolore.
4. Marionberry
5. Melon
   1. Cantaloupe
   2. Honeydew
   3. Watermelon
6. Miracle fruit
7. Mulberry

Unordered List#

• Olive
• Orange
  • Blood orange
  • Clementine
• Papaya
• Ut aute ipsum occaecat nisi culpa Lorem id occaecat cupidatat id id magna laboris ad duis. Fugiat cillum dolore veniam nostrud proident sint consectetur eiusmod irure adipisicing.
• Passionfruit

Horizontal rule#

In dolore velit aliquip labore mollit minim tempor veniam eu veniam ad in sint aliquip mollit mollit. Ex occaecat non deserunt elit laborum sunt tempor sint consequat culpa culpa qui sit. Irure ad commodo eu voluptate mollit cillum cupidatat veniam proident amet minim reprehenderit.

In laboris eiusmod reprehenderit aliquip sit proident occaecat. Non sit labore anim elit veniam Lorem minim commodo eiusmod irure do minim nisi. Dolor amet cillum excepteur consequat sint non sint.

Code#

Inline code#

Ad amet irure est magna id mollit Lorem in do duis enim. Excepteur velit nisi magna ea pariatur pariatur ullamco fugiat deserunt sint non sint. Duis duis est code in text velit velit aute culpa ex quis pariatur pariatur laborum aute pariatur duis tempor sunt ad. Irure magna voluptate dolore consectetur consectetur irure esse. Anim magna <strong>in culpa qui officia</strong> dolor eiusmod esse amet aute cupidatat aliqua do id voluptate cupidatat reprehenderit amet labore deserunt.

Tables#

Highlighted#

Et fugiat ad nisi amet magna labore do cillum fugiat occaecat cillum Lorem proident. In sint dolor ullamco ad do adipisicing amet id excepteur Lorem aliquip sit irure veniam laborum duis cillum. Aliqua occaecat minim cillum deserunt magna sunt laboris do do irure ea nostrud consequat ut voluptate ex.

package main

import (
    "fmt"
    "net/http"
)

func handler(w http.ResponseWriter, r *http.Request) {
    fmt.Fprintf(w, "Hi there, I love %s!", r.URL.Path[1:])
}

func main() {
    http.HandleFunc("/", handler)
    http.ListenAndServe(":8080", nil)
}

tmux set -g status-right "#[align=absolute-centre]#[fg=#f8f9f2]#W#[fg=#51cd97]#{?client_prefix,#[fg=#d0689d],#[fg=#51cd97]}.#[align=right]#{?window_bigger,[#{window_offset_x}#,#{window_offset_y}] ,}#[fg=#404040,underscore]#S#[none] "
tmux set -g status-style "bg=#1f1f1f,fg=#f8f8f2"
tmux set -g window-status-current-format "#{?client_prefix,#[fg=#d0689d],#[fg=#51cd97]}"
tmux set -g window-status-format "#[fg=#404040]"
tmux set -g status-left ' '
tmux set-window-option -g pane-border-style "fg=#404040"
tmux set-window-option -g pane-active-border-style "fg=#51cd97"

Ex amet id ex aliquip id do laborum excepteur exercitation elit sint commodo occaecat nostrud est. Nostrud pariatur esse veniam laborum non sint magna sit laboris minim in id. Aliqua pariatur pariatur excepteur adipisicing irure culpa consequat commodo et ex id ad.

Diagrams#

Mermaid turns text into diagrams. A fenced code block with the mermaid language renders one, and so does the mermaid shortcode. Each diagram is rendered to an SVG at build time and inlined into the page, so no JavaScript ever ships and the site keeps its no-external-requests rule.

Flowchart#

The example below is this site’s own deployment pipeline, end to end: a git push at the desk, through the homelab, out to the Cloudflare edge and finally into a reader’s browser. The full story lives in My Blog Now Ships From My Homelab!.

Sequence#

The same pipeline again, compressed into a handshake. This one is a plain mermaid fence instead of the shortcode. Both forms render the same way.

Inline elements#

Sint ea anim ipsum ad commodo cupidatat do exercitation incididunt et minim ad labore sunt. Minim deserunt labore laboris velit nulla incididunt ipsum nulla. Ullamco ad laborum ea qui et anim in laboris exercitation tempor sit officia laborum reprehenderit culpa velit quis. Consequat commodo reprehenderit duis irure esse esse exercitation minim enim Lorem dolore duis irure. Nisi Lorem reprehenderit ea amet excepteur dolor excepteur magna labore proident voluptate ipsum. Reprehenderit ex esse deserunt aliqua ea officia mollit Lorem nulla magna enim. Et ad ipsum labore enim ipsum cupidatat consequat. Commodo non ea cupidatat magna deserunt dolore ipsum velit nulla elit veniam nulla eiusmod proident officia.

Proident sit veniam in est proident officia adipisicing ea tempor cillum non cillum velit deserunt. Voluptate laborum incididunt sit consectetur Lorem irure incididunt voluptate nostrud. Commodo ut eiusmod tempor cupidatat esse enim minim ex anim consequat. Mollit sint culpa qui laboris quis consectetur ad sint esse. Amet anim anim minim ullamco et duis non irure. Sit tempor adipisicing ea laboris culpa ex duis sint anim aute reprehenderit id eu ea. Aute excepteur proident Lorem minim adipisicing nostrud mollit ad ut voluptate do nulla esse occaecat aliqua sint anim.

Incididunt in culpa cupidatat mollit cillum qui proident sit. In cillum aliquip incididunt voluptate magna amet cupidatat cillum pariatur sint aliqua est enim anim voluptate. Magna aliquip proident incididunt id duis pariatur eiusmod incididunt commodo culpa dolore sit. Culpa do nostrud elit ad exercitation anim pariatur non minim nisi adipisicing sunt officia. Do deserunt magna mollit Lorem commodo ipsum do cupidatat mollit enim ut elit veniam ea voluptate.

Reprehenderit non eu quis in ad elit esse qui aute id incididunt dolore cillum. Esse laboris consequat dolor anim exercitation tempor aliqua deserunt velit magna laboris. Culpa culpa minim duis amet mollit do quis amet commodo nulla irure.

Callouts#

Nostrud ex consequat id incididunt proident ipsum minim duis aliqua ut ex et ad quis.

Images#

Every image on this page is Unsplash stock, hosted here so the site keeps its no-external-requests rule. Click any of them to zoom in. Click again, or press Escape, to put it back.

Single#

A lone image takes the img shortcode: a figure, an optional attribution underneath and the zoom.

Aute officia nulla deserunt do deserunt cillum velit magna. Officia veniam culpa anim minim dolore labore pariatur voluptate id ad est duis quis velit dolor pariatur enim.

Strip#

A run of images scrolls sideways in the strip shortcode. Each image keeps its own zoom, and its credit follows it into the lightbox.

Labore ea magna Lorem consequat aliquip consectetur cillum duis dolore. Et veniam dolor qui incididunt minim amet laboris sit.

Masonry#

The masonry shortcode packs a wall of mixed heights into columns. Same zoom, same credits.

Ex amet id ex aliquip id do laborum excepteur exercitation elit sint commodo occaecat nostrud est.