My microscopic blogging framework

This website is not complicated. I have always wanted to keep this website not complicated. Web frameworks are so often a mess of libraries and APIs that get stale after a few years without active maintenance. This is a personal website, I have no interest in spending an undue amount of time maintaining it.

It's for that reason that I maintained this site as raw HTML for the better part of the last three years. Raw HTML is simple, flexible, and doesn't require any build tooling. I just point Netlify at the GitHub repository that hosts this site and I'm done.

Still, raw HTML can be a bit of a mess. There's a lot of boilerplate to maintain (like copy/pasting the same header into every page) and some simple things like inserting links produce relatively ugly source files. HTML is also relatively awkward for blog posts that require lots and lots of text -- I use linting tools to keep things "clean" but the indenting is just a bit of a nuisance.

So, as simple as raw HTML is, I've wanted to move over to a markdown based system for quite a while now. Most of my note-taking happens in apps that natively export nicely formatted markdown (mostly Bear) but don't always produce the type of HTML I'd been writing. Since a lot of my posts start as notes, it's convenient to be able to copy/paste stuff directly onto this site.

My major holdup with moving to markdown was the need for some sort of build tooling. Having absolutely no build tooling for this site was an aesthetically choice. Eventually, though, it became clear that the value of being able to write more easily was worth the hit to my aesthetic ego. My goal therefore became to create a minimal tool for converting this site to markdown -- something that could retain the aesthetic appeal of a minimal build system while still being powerful enough for everything I needed.

Enter nanoblog! nanoblog is a tiny tool for converting a markdown folder structure into html. The whole thing is about 50 lines of JavaScript (no TypeScript, just to keep things simple). nanoblog essentially just finds the markdown files in an input folder, compiles them into HTML, and then copies those output files and any other non-markdown files into an output folder. It's really quite simple.

nanoblog is pretty opinionated. It enshrines the template format that this blog uses and it assumes you have a single css file called style.css in the root of your input directory. Every page uses the same template and the same style.css file.

I might add some very light configuration to allow you to customize the template file, but that's probably the extent to which I'll make things more general. nanoblog is not meant to be a general-purpose system. That's the point! It's a tiny little thing that does one job and does it well.

Anyway. nanoblog isn't a groundbreaking project but I had a lot of fun putting it together. Although I wince a little at the presence of a package.json in the repository that stores this blog, it's ultimately been worth it. I was able to throw this post together quickly. I didn't have to copy/paste HTML from another file. My source directory is neatly stored away in a /src folder so the file structure looks even cleaner, in a way. And the site still looks the same! So, I'm happy.