101 lines
4.2 KiB
Markdown
101 lines
4.2 KiB
Markdown
---
|
|
title: Building My Own Static Site Generator
|
|
date: 2025-07-10
|
|
draft: true
|
|
description: |
|
|
An overview of static site generators and my experience of developing Zona.
|
|
---
|
|
|
|
*[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.
|