---
title: Building My Own Static Site Generator
date: 2025-07-10
draft: true
---

*[SSG]: Static Site Generator

[homebrewed]: https://en.wikipedia.org/wiki/Homebrewing
[zona]: https://git.ficd.sh/ficd/zona
[Hugo]: https://gohugo.io/
[Zola]: https://www.getzola.org/
[Jekyll]: https://jekyllrb.com/
[Zoner]: https://zone-builder.neocities.org/
[Zonelets]: https://zonelets.net/
[Neocities]: https://neocities.org

[^jd]: [jdugan6240.dev](https://jdugan6240.dev/posts/custom_site_generator.html#why)

[^long-sentence]: I disabled the "long sentences" linter in my grammar
    checker. Take that for being unapologetic!

[^small-web]: The "small web" is a way to collectively refer to
    independent, home-made, personal websites --- often with a focus on
    creativity, anti-capitalism, and technology.

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 blog post you're reading. Without any further ado, let's get
into it!

[TOC]

## Zonelets & Zoner

I don't remember how I found out about the small web,[^small-web], but I
_do_ recall how it immediately sparked something in me. As an autist with
very particular interests that's always struggled to fit in, the premise
of having my very own corner of the internet where I could
unapologetically be myself without fear of retribution from rude
social-media commenters or being subject to the whims of some grumpy
content moderator was _very_ appealing to me.[^long-sentence]

## 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.

## Snakes Eating Gophers: A Valiant First Attempt

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 to learn the language better.