My static site generator series (2024/05/29)

My static site generator series

2024-05-29 09:30:00 +07:00 by Mark Smith

This short blog series is a first attempt at describing my latest development project. I've been working on the static site generator for a couple of years on and off, as life permitted, with very limited resources. It was born out of the ashes of my linkblogging SaaS project. Initially just to build my own personal website, but it's become much more of a generalised website builder over time.

The personal website, by the way, is very minimalist. That's partly a personal preference, I feel like information based websites should focus on text. I also wanted to have a site that would render with or without javascript enabled in the browser, readable on desktop and mobile. The plan is to enhance this over time using all the glorious modern CSS features that exist. For the moment though it's very minimalist. The way to think about it is that underneath the minimalist outward appearance, there's a lot of cool things happening to generate all the pages. Making the website look cool will be possible relatively easily using things like over-riddable server side components. Things take time when you are building the tool you are using, you have to build the foundations first.

In any case, before embarking on the static site generator project I did of course survey available tools. I had experience building my personal blog with Jekyll, but since I'm a Nodejs developer, I really wanted something written entirely in javascript. When I looked at existing javascript generators, though there were some great options available, I found that building the archives for my existing site to be overly complex. When I openned the hood to delve into the source code, things felt again very complex and somewhat convoluted.

These were great tools, but I got the sense that whatever hard won battles they had been through had resulted in code that, at least for me, was very difficult to fully comprehend. I wanted to be using a tool that I fully understood, both as a user, but also as a developer. I wanted the ability to modify the tool should that be necessary. I felt the best way to do this was to build a static site generator from scratch, optimised for building my personal website, but general enough that it could be used for other websites too.

That's basically the backstory, but I've also recently wrote a longer term vision which you might find interesting. In it I go into the some of the values I've developped over the years when it comes to developing software, and the general direction I see things going for this project into the future.

Like I said in the opening paragraph, this is just a first attempt at describing the tool's high level functionality. It's not meant as documentation or as a user manual. It's a bit technical but it's more aimed at generating some interest in the project. The project is not currently released as open source, but that's absolutely part of the longer term plan. Sometimes life throws you a lot of curve balls, and that's certainly been the case for me the past few years. Also, knuckleballs. This is the best I can do at the minute with the severely restricted resources that I have available to me.

So onto the static site generator features overview, let's start with some of the smaller but very useful stuff, these include clear readable code, rendering in batches, easily follow the flow of data through the render process, easily debug the render process, Github build/deploy/backup workflows, highly customisable render process, page layouts and configuration management.

Now some of the more meaty stuff. Here's a non exhausted list of some of the more major features and concepts:

I hope you enjoyed this overview. It's still early days for this project, but if this at all peaked your interest then get in touch with me.