ficd/ficd.sh
1
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

write more of ssg draft post

Browse source
This commit is contained in:
Daniel Fichtinger 2025-07-10 20:20:14 -04:00
parent 763a80a96b
commit fd8d829d77
1 changed files with 60 additions and 39 deletions
Download patch file Download diff file Expand all files Collapse all files

99
content/blog/building-my-own-ssg.md
View file

@ -1,71 +1,91 @@
--- ---
title: Building My Own Static Site Generator title: Building My Own Static Site Generator
date: July 6, 2025 date: 2025-07-10
draft: true draft: true
--- ---
*[SSG]: Static Site Generator *[SSG]: Static Site Generator
*[homebrewed]: Self-made, intended for personal use. [homebrewed]: https://en.wikipedia.org/wiki/Homebrewing
[zona]: https://sr.ht/~ficd/zona [zona]: https://sr.ht/~ficd/zona
[Hugo]: https://gohugo.io/ [Hugo]: https://gohugo.io/
[Zola]: https://www.getzola.org/ [Zola]: https://www.getzola.org/
[Jekyll]: https://jekyllrb.com/ [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) [^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 [^long-sentence]: I disabled the "long sentences" linter in my grammar
do — and passion often manifests itself in _blogging_. Rolling your own blogging checker. Take that for being unapologetic!
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 [^small-web]: The "small web" is a way to collectively refer to
we have over them? Many of the programmers I respect publish blogs using a independent, home-made, personal websites --- often with a focus on
homebrewed SSG. I figured it was time to join them! 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 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 rendered the blog post you're reading. Without any further ado, let's get
into it. into it!
[TOC] [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 ## Reinventing The Wheel
There's no shortage of excellent SSG tools out there. [Hugo] is fast, 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 configurable, and very popular. [Jekyll] is the default on GitHub pages,
makes it _(I'm guessing)_ the most commonly-used SSG by a long shot. [Zola] is which makes it _(I'm guessing)_ the most commonly-used SSG by a long shot.
tiny, dependency free, and _very_ flexible. [Zola] is tiny, dependency free, and _very_ flexible.
You can certainly build some awesome blogs with these tools, and customize them You can certainly build some awesome blogs with these tools, and customize
as much as you want. For example, my friend Alisa uses [Zola] to publish them as much as you want. For example, my friend Alisa uses [Zola] to
[her blog](https://axlefublr.github.io/), which is a great example of how a publish [her blog](https://axlefublr.github.io/), which is a great example
minimal website can truly shine with the right styling and customization. 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 So: if there's such an abundance of great static site generators, why did
write my own? JD[^jd], a fellow Kakoune enjoyer, puts it well: I write my own? JD[^jd], a fellow Kakoune enjoyer, puts it well:
> 1. It's a good learning experience \[...\] > 1. It's a good learning experience \[...\]
> 2. Many static site generators are complex and take time to learn to configure > 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 > 3. A custom solution grants complete control over how exactly the site
> generated \[...\] > is generated \[...\]
My main motivation for starting work on [zona] was the third point: **complete My main motivation for starting work on [zona] was the third point:
control**. I don't think being a control freak makes me an outlier among Linux **complete control**. I don't think being a control freak makes me an
users — why else would we be breaking our operating system near-daily, if not outlier among Linux users — why else would we be breaking our operating
for some obsessive customization? 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 It's happened very often that I find some tool I like, and during the
tweaking it, I find _something_ that can't be changed --- which ends up process of tweaking it, I find _something_ that can't be changed --- which
bothering me immensely. I figured that I'd rather avoid this experience while ends up bothering me immensely. I figured that I'd rather avoid this
writing my own blog. This way, if something is missing, it's my fault, and no experience while writing my own blog. This way, if something is missing,
one else's. it's my fault, and no one else's.
## Requirements ## Requirements
The features I implemented in [zona] are informed by what I want from my own The features I implemented in [zona] are informed by what I want from my
blog. The primary user is myself, after all! I knew I wanted: own blog. The primary user is myself, after all! I knew I wanted:
- Writing in Markdown with as little embedded HTML as possible. - Writing in Markdown with as little embedded HTML as possible.
- A convenient live preview. - A convenient live preview.
@ -74,7 +94,8 @@ blog. The primary user is myself, after all! I knew I wanted:
- Declarative configuration. - Declarative configuration.
- An easy way to add new posts. - An easy way to add new posts.
## Gophers And Snakes ## Snakes Eating Gophers: A Valiant First Attempt
I started work on [zona] in October, 2024. At this point, I had written a few I started work on [zona] in October, 2024. At this point, I had written a
(smaller) projects in Go, and I wanted to work on something more complicated. few (smaller) projects in Go, and I wanted to work on something more
complicated to learn the language better.