Rewriting my website for fun and no profit

After 2 years of no activity, I've realized that.. I'm not really good at writing posts. When I'm doing something that could make for great post material, I simply don't have motivation to write things down, much less in a format that would be coherent to anyone but me. However, how else can I improve than just practicing? And as such, join me on this adventure, while I rewrite my website engine to suit my needs better!

...what?

Well, this is the fun part - writing code brings me way more joy than writing prose. Code is way more strict in its grammar, and has a clear goal to achieve; text is fluid, chaotic. But then, if I work on my website, it gives me an opportunity to actually write about it, and possibly complete my goal of writing single post in 2025.

goals

Hugo, the current engine behind the website, has always annoyed me a bit. It was alright-ish in terms of features, but anytime I wanted to do something more custom, the documentation was less than helpful, and I would either abandon the idea or get stuck reading the engine code itself. How hard can it be though? It's just joining a few HTML files together, converting some of them from Markdown, and templating a few files with the list of posts.

Ideally, I would love just a small thing that I can extend whenever necessary, but still just generating plain (and easy to read) HTML files. I'm also not scared of writing raw HTML, so stuff like "generating the footer links from a TOML structure" is mostly unnecessary; automatic RSS generation and syntax highlighting are a must-have though.

initial implementation

In the past I used mostly Go and JS for quick prototyping, but lately I've found myself feeling more comfortable with Python; with that in mind, I decided to go for a simple Python script, powered by python-markdown. There's just something really satisfying about a website that can mostly build itself, with just a handful of dependencies, rather than a massive third-party executable.

With these things in mind, I decided to write a tiny proof-of-concept – generate the front page by reading blog post metadata. Hugo's metadata format is simple enough, being just a YAML-like document plopped into the file header.

For templating, I decided to go with Mako. Jinja2 was a tempting choice, but being a DevOps by trade, I have to deal with Jinja's design choices every single day at work; it would be nice to have something more comfortable back at home :3

Okay, let's get to writing code: import markdown, import mako, iterate over the files, render each to HTML-

wait, we're done?

...almost.

As it turns out, a page consisting of a front page and some blog posts really isn't hard to render - all we needed is two templates, and some glue code to mash the Markdowns into HTMLs. python-markdown already provides a meta_data module to parse the YAML-like metadata into values we can read, and setting up Pygments for syntax highlighting needs simply generating the CSS files with pygmentize.

Adding proper Atom support was a bit more tricky - there's libraries like feedgenerator, but they don't support the 'content' Atom field, instead using just the description. The solution? Just add another template, but for the feed, writing the XML by hand. Alas, there's a drawback to putting all the posts into one large feed: right now, the feed is around 200 KiB in size, and it will grow with every single new post; it's not too much though, and IMHO being able to read the blog entirely from a feed reader is a nice addition, even though some of the styling will be lost.

(also, hopefully most feed readers can actually stream HTTP+XML just until they read the updated field, and stop reading if it hasn't changed, though it's not the end of the world if they don't.)

conclusions

I'm... not really sure what I expected about this post. When writing all of this, the main challenge wasn't either the code, or even the blog post, but actually staying focused enough to finish either. I was really hoping for "actually, it's not that easy", but, well, it really was that easy - all 56 MiB of Hugo code was replaced with one Python script and three dependencies.

Realistically though, Hugo can support way more than my silly little script. There's pagination, asset processing, and all the little things that I simply never needed. But, after all, the purpose of this wasn't to write a replacement to a massive framework; instead, it was to make something tailored for my purposes, and I think I managed to achieve that quite well.

Even worse, my writing style is still as annoying as ever - even re-reading what I just wrote feels like random rambling without a direction. Maybe it would be better to write it like a presentation script, with vague directions related to what's on the slides? Or maybe a question-answer style like many other writers adopted, where I make up a character to help along with the explanation? Who knows! It's something for future me to worry about.