I Turned My Hugo GitHub Style Activity Tracker Into a Reusable Module

kalsdjf23 — Tue, 10 Mar 2026 19:56:50 +0000

I first built this GitHub style activity tracker for my own website.

That part was already fun. I liked seeing my publishing streak in the same kind of grid GitHub uses. But once it worked, I started wondering whether this was just another thing that only made sense on my site, or whether it could become something other Hugo users could actually use as well.

So I tried to make it generic. The module is here:

https://github.com/kalsdjf23/hugo-activity-heatmap

The hard part was not building it

The first version was tied to my own site and my own content structure. That is fine when you only build for yourself. It becomes a problem the moment you want to share it.

I had to strip out all the assumptions that were specific to my setup. Things like section names, wording, labels, and how the data was interpreted all needed to become customizable.

The final module can now:

work with any Hugo section, or with all regular pages
use Date, PublishDate, or Lastmod
render either a binary or density heatmap
change the wording used in labels and counts
optionally show a start date
work without JavaScript

Open source has a quality bar

What surprised me most was not the code. It was the process around it.

To submit something like this properly, the repo also needed all the grown-up stuff:

a proper README.md
a theme.toml
a root hugo.toml
a license
preview images
an example site

When I build for myself, I usually want to skip all of that and move on. But if other people are supposed to install your work, that structure matters more I guess.

Why I wanted to publish it

I have used open source for years without really contributing anything back.

Not because I did not want to. More because I rarely felt productive enough to make something that was clean and complete enough to publish.

This time I had something that felt worth sharing.

I also submitted it to the Hugo themes directory, so now it is in the hands of people with a much higher quality bar than mine.

If you want the full story behind the build, the screenshots, and the themes-directory submission, I wrote that up here:

Can I contribute a Hugo component to open source?

Forem: kalsdjf23

I Turned My Hugo GitHub Style Activity Tracker Into a Reusable Module

The hard part was not building it

Open source has a quality bar

Why I wanted to publish it