SSG Adventures

2026-08-09T00:00:00+00:00

It's practically a given that every user of IndieWeb should have as their first post a text explaining their initial misadventures creating and deploying their personal website.

My case is no exception. I originally tried to bring my site to life, first by creating my own SSG (Static Site Generator), of which remnants still remain. Shortly after, I realized the complexity of this task, and with university still consuming much of my time, I decided to put this project on hold for a while.

With this article, I want to test the writing and format of a blog, and discuss the creative and design process that led to the current technology stack of dobon.dev.

And in the beginning there was lobste.rs

My interest in having my own digital space goes back a long way. Accidentally, while trying to resolve the various doubts that arose during my self-taught journey in the world of computing, I came across texts that I found very interesting and educational, as in many cases they opened the door to completely new concepts.

Michael Stapelberg's explanations of his experimental package manager d1stri, Xe Iaso's detailed explanations of his paranoid NixOS configuration, and Aria Desires' rant about the current state of C-based ABIs were small windows into everything in my field that I didn't know.

It was therefore natural for the desire to write and share my opinions and discoveries to arise within me, a desire that remained latent but constant throughout the years. Upon arriving at university and speaking with my peers, I realized that perhaps I had underestimated both my ability to teach and show others my discoveries, and the pleasure I derive from doing so.

After the first semester, somewhat more settled in university life, I decided to dedicate my scarce free time to building my own website. During that period, while routinely browsing lobste.rs, I came across a new, clear, and direct entry: Why You Should Write Your Own Static Site Generator (entry on lobste.rs).

Motivated by this article, I opened RustRover with the intention of creating a SSG that would fulfill a short and humble list of features:

Incremental rendering.
Rendering based on HTML templates.
Multilingual support.
Atom font generation.
AVIF image optimization and generation of WEBP and JPEG fallbacks.
Hot reloading.
Taxonomy system.
Comment support with Webmention.
Minification of HTML, CSS, and JS.
POSSE syndication.

I hope the irony is clear... Looking back, my mistake is obvious; the complexity of the system I needed was far too high. Development quickly became an uphill battle due to the second semester, which was already running at full capacity, and a series of self-imposed restrictions, I wanted it to be a fully-fledged general-purpose SSG, not a houseplant program.

All of this led to the project ending prematurely, dissatisfied with what I had managed to achieve. I believe there were a few key points that made the task much more difficult:

I underestimated the difficulty of creating a functional cache and the limited need for incremental rendering in most SSGs, given the rendering speeds they can achieve.
Converting between image formats proved to be more complex than simply adding
an extra library and function call. ImageMagick has a highly complex API.

In short:

There are only two hard things in Computer Science: cache invalidation and naming things.

— Phil Karlton (source)

Hugo Makes Me Dizzy

I was away from this topic for a while; a self-hosting project, which I want to write about in the future, took up a lot of my time.

Just as August was beginning, I decided to finally have my own website, and I chose Hugo, which is undoubtedly, along with Jekyll, Eleventy, and Astro, one of the most widely used SSGs in the world...

It wasn't a productive afternoon; Hugo's documentation turned out to be a disaster More like a reference guide than a document that helps you learn how to use the tool, it constantly introduces new concepts and links too many pages together, making the whole thing overwhelming.

Their Quick start guide treats the tool as a black box, forcing the installation of a theme, as it doesn't explain how the template and styling system works.

Hugo's Glossary

This section wasn't originally going to be hidden behind a dropdown, but I made it too long. Besides, it ended up sounding too much like a rant.

An example of this problem is his glossary of terms, which has many issues such as:

The addition of common computer terms that only make the glossary too long, for example:
- Boolean: A boolean is a data type with two possible values, either true or false.
- Cache: A cache is a software component that stores data so that future requests for the same data are faster.
- CLI: CLI stands for command-line interface, a text-based method for interacting with computer programs or operating systems.
— The Hugo SSG Glossary (source)
The existence of proxy terms, for example:
- Dimension of content: See dimension.
- Bundle: See page bundle.
- Bool: See boolean.
— The Hugo SSG Glossary (source)
The invention of unnecessarily complex terminology:

Dimension: A dimension is a categorized axis of content variation that allows multiple variations of a logical page to exist simultaneously. The three dimensions are language, role, and version. For example, a logical page may exist in 6 languages, 4 versions, and 2 roles.

— The Hugo SSG Glossary (source)

Don't get me wrong, this glossary isn't a critical issue, but it perfectly exemplifies the poor state of Hugo's documentation.

What if I use Bash?

For a very brief period, I considered not using an SSG, but rather a series of Bash scripts that would utilize tools like Pandoc or yq.

The idea lasted only an afternoon. I quickly realized how it would end up with the same problems as my original attempt at an SSG, and I also remembered my hatred of shell scripting.

Using Zola

Finally, I gave a second chance to a tool that once performed flawlessly and that I still don't know why I abandoned: Zola.

I have no complaints. Its Getting Started - Overview quickly guided me in creating a simple personal blog, demonstrating the functionality of its template system and its concise terminology based on pages, sections, and indices.

It's a SSG that aims to be fast, unobtrusive, and offer just the right amount of functionality.

Let's Talk About Open Source

On a more personal note, I was pleased to see that the project transitioned from a MIT licence (permisive) to the EUPL (libre and viral). I'd like to include the following excerpt from a conversation that took place on GitHub:

Unfortunately there is a massive change for corporate users in the US. EUPL is categorically prohibited across the tech industry as it gets lumpedin with AGPL and SSPL. This license effectively makes zola impossible to even run the binary in any US commercial setting. — psarossy

Too bad for US corporate users then? No reason to lump EUPL with AGPL. [Version] 0.21 is still available for those users. — Keats (creator of Zola)

— Excerpt from the conversation in Issue #3093 of the Zola GitHub repository (source)

I think it perfectly illustrates the asymmetrical situation we find ourselves in the Open Source world. The corporate and professional world has created a set of expectations over volunteers and people who practice computer science as a hobby, forcing them to provide products and services of excellence and business-ready.

I think it's relevant to reiterate a series of often-forgotten truths:

Everyone is free to create when and how they want, regardless of whether what they create has practical use.
You are under no obligation to examine Pull Requests or any other proposals for adding code, whether written by a human or AI.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

I highly recommend the text help wanted by Lake Hope, which explores this topic in greater depth.

Post mortem

On the one hand, I'm very happy to finally have a place to share my ideas and opinions. But I can't help thinking that I haven't managed to develop the necessary skills of a software engineer; burnout, exhaustion, and a lack of knowledge have played a key role in this, but not having been able to develop a more competent SSG program leaves me with a bittersweet feeling.