Finally, a website!

Finally, after checks notes four or five years of having a placeholder homepage on my domain, and probably even more of owning it, I actually have a website.

So, how did I finally do it, or rather, how did I not do it earlier, and what changed?

Now, when it comes to the internet I generally dislike a bunch of JavaScript and hundreds of megabytes of images when it is not necessary.1 If you're serving me text with some formatting, just give me some static HTML and CSS and be done with it!2

^1 one place a bunch of JavaScript isn't unnecessary, is cool demo websites like this one made by one of my classmates
^2 I get especially annoyed when I'm on the road or in the mountains so don't have good internet access, and I can't access a basically-text-only webpage because fetching the content keeps timing out or being interrupted by drops in internet

Because of this, I've always wanted my website to be a simple affair, just some static pieces of HTML with some CSS to spice things up, and not a speck of JavaScript in sight. Okay, I might want a demo here or an applet there, but in my general, everyday pages there shouldn't be any JavaScript.

This means that I'm not interested in making a site with something like React, and definitely not Wordpress either.

Lost in the desert

So, no big deal, you might say. Plenty of ways to get that done. And indeed, you would be right; That is, were I not so picky.

One option you might propose it to just write HTML by hand – plenty of people have done it3. The problem in this approach, lies in the fact that HTML does not come with any sort of built-in templating. This means if I want some sort of a common element, a navbar or next/previous buttons for blog entries, for example, I don't have a nice way of doing that automatically with just HTML. I could enter the same thing in every single page, yes, but what if I want to add a link to the navbar? What if I want to change a piece of text? Now I need to update every. single. page. on the whole website. And I'm a programmer, we'll spend hours automating something that would take minutes to do manually4; how much more would I want to optimise a repetitive task where I could easily miss a spot, which could eventually take hours5 to do if my site grew large enough?

^3 relevant xkcd, and another
^4 for a selection of handwritten websites, you might be interested in https://neocities.org/, which hosts quite a few very impressive and creative websites
^5 okay, so maybe hours is a bit overoptimistic, I doubt my site will grow that large, but even if it took fifteen minutes that'd be quite annoying

That, and writing <!DOCTYPE html> <html><head> bunch of random nonsnes </head><body> actual content </body></html> each time gets really boring and really repetitive really fast. And I get bored easily.

The easy solution in that case is to use some sort of a static site generator. I'm sure I could have just use some standard tool in a language I was familiar with, like Flask, but here is where some of my peculiarities come in.

For one, I like being in control and doing things my way. If I'm going to write a blog post, I'm putting it where I want to put it, I don't want to be forced into a specific paradigm of how I should structure my website.

And this also extends to the HTML: I don't want whatever I use to stuff in a bunch of random CSS files and meta tags in my header – I need to know what everything there does, and I need to be able to remove it if I don't like it.

Then I also like reinventing the wheel, and I want to understand what I'm using completely. I don't want to write a python file and use random functions I found in the documentation or a tutorial somewhere, and roughly cobble something together. I mean, I can do that, I often do do that if I don't care about the exact mechanisms. But if I'm making my site, I want to know how it works!

Another problem, is that I want to make a multilingual site. I'm fluent in two languages already, and hope to learn more as time goes on, and so I want to make my website available in multiple languages. And so whatever I use must support this, and support it well – I want to have my navbar translated when I write a page in a different language. I want the lang attribute of the outer html tag to correctly vary between en-ZA, af, and whatever else. And, once again, I don't want to be forced into your way of segregating the different languages, and your way of serving pages translated into different languages. I want to do it my way.

Lastly, whatever I use must allow me to at some point start using MathJax or something similar; after all, I love mathematics, and am now studying Mathematics at university (along with CompSci of course), so I'd likely want to add math content to my website at some point.

So what does this mean I need in a static site generator?

And so, over the years, I tried various SSGs. And I'm sure there are plenty that do fit my requirements, but I just did not spend enough time on them, or encountered too much friction trying to do stuff my way rather than how the SSG wants me to do it.6

^6 I recall that I had quite a bit of success with a cool SSG, hastysite, which came with a cute little stack-based programming language, but had issues because the page language was hard-coded as English, and at the time I couldn't work out a nice way of fixing that

And of course, through this time, I also tried various times to write my own SSGs, typically in Python. Sometimes I'd do the markup to html conversion manually, other times I'd use some library, and I'm sure at times I just wrote a program to stitch HTML fragments together. However most of these personal projects inevitably faced over-engineering, scope creep, and eventual abandonment once they were no longer maintainable or fun to work on.

The promised land at last

In the last few years, however, I've started programming in C recreationally, inspired in large part by Tsoding, where I started learning about minimalism and how to really just work on a program one feature at a time rather than overgeneralising for hypothetical future use-cases. Then last year, I started successfully working on various long-term projects, which would actually last months and reach usable states, rather than my old practice of writing a program for a week or two before abandoning it completely. Along with this, I worked on a few small projects which I'd complete in a matter of days or weeks.

This mindset of simplicity, working on the current problems before me rather on hypothetical future usecases, and actually sticking to my projects, eventually helped me greatly in creating this static site generator. I started after being inspired by Tsoding's video on Jai's metaprogramming capabilities, where he creates a vaguely similar SSG in Jai. In the video, he created a templating system, where Jai itself is used for "scripting" (loops, substitutions, etc), and file contents was output to standard output. Coupled with my experience with nob.h, as well as that I had previously made a two stage build system with it, I decided to give making a similar SSG a shot, where I'd use C for any scripting needs and keep the templating as simple as possible.

And it worked! At last, I have an SSG I'm happy with: one that's simple, one that I have a complete understanding of, one that I have complete control over, one that's powerful enough to do all I want, and probably quite a bit more – after all, I create the HTML pages by writing and running C programs, so every page in the website is created using a Turing-complete programming language.

Some interesting reads

Vaguely related articles which you might enjoy

Initial html generated from markdown by md2html
First draft available as a 48-minute recording here
Transcription of first draft by whisper.cpp available here

← Previous entry | “Simple” Bash Hello World — The Power of Lisp: Writing a Procedural Dialect | Next entry →