--- title: Building My Own Static Site Generator date: July 6, 2025 draft: true --- *[SSG]: Static Site Generator *[homebrewed]: Self-made, intended for personal use. [zona]: https://sr.ht/~ficd/zona [Hugo]: https://gohugo.io/ [Zola]: https://www.getzola.org/ [Jekyll]: https://jekyllrb.com/ [^jd]: [jdugan6240.dev](https://jdugan6240.dev/posts/custom_site_generator.html#why) 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](https://axlefublr.github.io/), 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? JD[^jd], a fellow Kakoune enjoyer, puts it well: > 1. It's a good learning experience \[...\] > 2. Many static site generators are complex and take time to learn to configure > \[...\] > 3. 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.