As part of my website progress, I'm going to 'fork' my website as it is going in a different direction
Published on
I have been sick for the entire last weekend. I have been partially bed/couch-ridden, but finally after regaining some strength to start coding some more Racket, here I am. Today marks the first day of a new step on the long staircase to my own static site generator - forking my website.
If you are confused by how I'm wording this, then please bear with me as I explain.
I don't have a good name for my current static-site generator (SSG), so I call him "Builder". I started work early-ish in February, and I think I'll be done with it by the end of the month of February, which I can say I'm mostly proud of. However, it won't be feature-complete, at least not yet. For me to say it's "done", it has to have feature-parity with what I use right now, that being Zola.
Let's recap again with why I'm doing this. There's a few reasons why, and I'll name a few.
Zola has a lot of features, like a SASS compiler for smarter CSS, a decent template system, asset manipulation, a local webserver for testing, and it being made in Rust lends itself to being a great tool for a fast write/preview loop.
Zola is pretty good at what it does, but it's not possible to currently re-create it with Guix. Rust packages are annoying to have to re-define with Guix, and my attempts have failed at creating a reproducible website with Guix. Moving forward in the future, I would like to be able to re-create my environments with Guix, or at least if not Guix, then something else. Reproducible environments are really helpful for developers.
This isn't necessarily a bad thing about Zola. It does work on Nix, but Nix is not my preferred system for reproducibility. Nix does not build from source, and relies on a very expensive cloud build system to try to satisfy everyone's needs in the world. Guix tries to build everything from source, and I think that's something I'm more personally interested in.
Regardless, Zola is partially in my way of a desired working environment. I have content, I have some web ideas, and I'd love to get this out of the way so I can move onto other things I have in mind to work on.
Zola uses TOML format for it's core configuration files, as well as content metadata. This, I really don't like. I just don't like TOML. I think it's lame, and for it's use in Zola, sort of boring. I don't know who uses TOML anywhere else other than Zola, and that's enough for me to say "I don't think I want TOML either".
My metadata in TOML looks sort of like this
+++
title = "A title, with quotes making it a string"
description = "another string, with more quotes"
date = 2024-01-01
[taxonomies]
tags = ["programming"]
[extra]
thumbnail = "self-defined property"
thumbnail_desc = "I put these two here myself"
+++
Currently right now, Zola supports a lot of weird features, one of them being taxonomies, which is supposed to help organize and group content by keywords. It's marked by the [taxonomies]
tag, but realistically, I don't use taxonomies for much more than that. There's also the [extra]
section to stuff additional variables that sit outside of Zola's structural definitions.
I do not wish to implement TOML in my program, and as such, this format is going to be unsupported. The main reason is that it's not supported by the standard Racket library, so I would have to bring in a third-party package, which just adds to the stress of having to maintain your own packages. I don't actually like TOML, so I don't see a need for it. There are some things TOML is good for, but I don't see an added benefit here, to be honest.
Instead, the new format will be pretty dead-simple by comparison.
+++
title = Hello world!
desc = A one-line description
date = 2024-01-01
tags = programming,general,etc
thumbnail = picture.png
thumbnail_desc = a line of text describing above image
draft = false
+++
The minimalism here is me deciding that most of these properties don't ever really exceed a one-line use-case. My title is never that long, my description is also generally not that long either, and parsing text by lines and splitting on a delimiter is just way easier than implementing TOML.
This, however, implies that all my content on Zola is now effectively not future-compatible with my future website generator. So, as thus, this is where I will need to "fork" my website.
The website generator is not quite production-ready. I expect it will take a week or two more, give or take based on my available time. In the mean time, I will be copying over all my Zola content to a separate folder that I will maintain in parallel. It's basic hedge pruning at best, where I go through some old files, modify it to make it compatible, then work as best as I can to get my generator off the ground. I might even go backwards and add additional thumbnails or tweaks, or possibly remove things that I am less pleased with. We'll see.
I start by doing this:
$ cp -r content content2
Which copies all my Zola content to a separate folder, and I begin my tweaks from there. My generator will target the content2
folder for now, and that's how my tests are going to start. My templates
folder, which powers the layouts here, I expect will have little to no tweaks, as I am attempting to make my generator compatible with the template engine used by Zola (called Tera).
Tera has been pretty instrumental in teaching me about creating a rigid template engine, and the ideas given were nice. I don't have any abject issues with how the template engine works, I think it's pretty simple, and it's format follows that of many engines before it like Jinja2, which was often used with Django or Flask quite a bit.
Copying all my content and making the necessary changes to make it compatible is an unavoidable move, as I really don't want to have feature parity with that of Zola, so by the time this is all said and done, my transition to the new website will be less painful. Some layouts might change or break, but it was doomed to happen regardless.
Another breaking feature will most likely be how I "slug" the URLs. I'm at present not entirely happy with how my blog is currently slugged, so I will look to change that. Currently it uses a /blog/title
schema, but there could be a time where I have two identically-titled posts, and then what happens? I haven't messed much with the slugging of Zola, but I'm not going to think about that now. I would like to move to a /yyyy/mm/dd/title
format to avoid a duplicity problem, which will obviously break a lot of links for anyone who might have bookmarked something. Sorry.
The tag system is one thing I'd like to have stronger control over. Zola right now tends to generate RSS/XML feeds of every tag you have, and I'm sure you could limit this, but right now, I have a ton of extra RSS feeds sitting on this web page that probably don't need to exist. They all derive from a base rss.xml
template I have, but it's for every tag I have ever mentioned on my posts.
To get some granular control over this, I'm going to explicitly state which tags I would like to generate RSS feeds for. This will better cull user attentions, like those who are only interested in programming topics may find a feed for exactly that, while cutting out all the other junky posts that do not involve programming.
I'll keep this brief, as I tend to go on for way too long with posts. The Builder generator is not quite done yet, but I need test data for me to start the transition. I'll be going through my old posts and trimming hedges over the course of the day and seeing what I can prune.
There are no major changes to the website as of yet. There is a demo folder, but it's nothing without it's full contents quite yet. Once I have Markdown parsing at a working stage, I might just fire the trigger and build the rest of the features out as I go along. So long as I have a working blog feed and RSS, I think that would be considerably good enough for me.
Until next time.