3.1 KiB
| title | date | draft |
|---|---|---|
| Building My Own Static Site Generator | July 6, 2025 | true |
*[SSG]: Static Site Generator
*[homebrewed]: Self-made, intended for personal use.
Those of us in the open-source world tend to be very passionate about what we do — and passion often manifests itself in blogging. Rolling your own blogging setup seems to be a rite of passage. It's a project of moderate complexity, fun, and not particularly time-consuming.
Personal websites and blogs are very... personal. Why not maximize the control we have over them? Many of the programmers I respect publish blogs using a homebrewed SSG. I figured it was time to join them!
This article is about how (and why) I built zona, the SSG that built and rendered the very sentence you're reading. Without any further ado, let's get into it.
[TOC]
Reinventing The Wheel
There's no shortage of excellent SSG tools out there. Hugo is fast, configurable, and very popular. Jekyll is the default on GitHub pages, which makes it (I'm guessing) the most commonly-used SSG by a long shot. Zola is tiny, dependency free, and very flexible.
You can certainly build some awesome blogs with these tools, and customize them as much as you want. For example, my friend Alisa uses Zola to publish her blog, which is a great example of how a minimal website can truly shine with the right styling and customization.
So: if there's such an abundance of great static site generators, why did I write my own? JD1, a fellow Kakoune enjoyer, puts it well:
- It's a good learning experience [...]
- Many static site generators are complex and take time to learn to configure
...- A custom solution grants complete control over how exactly the site is generated [...]
My main motivation for starting work on zona was the third point: complete control. I don't think being a control freak makes me an outlier among Linux users — why else would we be breaking our operating system near-daily, if not for some obsessive customization?
It's happened very often that I find some tool I like, and during the process of tweaking it, I find something that can't be changed --- which ends up bothering me immensely. I figured that I'd rather avoid this experience while writing my own blog. This way, if something is missing, it's my fault, and no one else's.
Requirements
The features I implemented in zona are informed by what I want from my own blog. The primary user is myself, after all! I knew I wanted:
- Writing in Markdown with as little embedded HTML as possible.
- A convenient live preview.
- An easy way to write image captions.
- Control over the Markdown parsing.
- Declarative configuration.
- An easy way to add new posts.
Gophers And Snakes
I started work on zona in October, 2024. At this point, I had written a few (smaller) projects in Go, and I wanted to work on something more complicated.