Have Blog, Will Write
Wednesday the 14th of July 2021
Welcome to this newly created blog, my own personal place to shout into the void. I tend to have a fair amount of ideas I want to talk about and have long wanted somewhere better to put them than pestering folks in my resident Discord server. I expect the primary contents of this to fall into the category of random thoughts distilled into a handful of paragraphs.
To get the ball rolling let's talk about how this blog was assembled.
I love plain text. A flat text file contains an amazingly surprising level of expressiveness when allowed to stretch its wings. Chief among the tools which enable this level of greatness is Markdown, the most blessed of formats, hallowed be its name. I love Markdown, in its ubiquity and in its quirks.
So this is my first requirement for a blogging solution. I want to write in Markdown and get a pleasant looking webpage out the other side. What else do I need? I'd like to have a main page with a list of posts. So far so standard. Having an RSS feed is also something I need. This is starting to look suspiciously like the feature list of a blog generator.
I had previously looked in blog generators and been underwhelmed with regards to the amount of control they expect to have over blog structure. More frustratingly was how dang complicated it looked to create a custom theme. I don't want another generic looking blog, I want it to stand out. So a few weeks ago, feeling a bit under-productive, I decided to just write my own. I took a few days to work on that, felt better, and returned to my main project working on getting familiar with Vulkan. Now I've returned to clean it up and start using it :)
Building this blog generator was really quite trivial. I'm leaning on the excellent pulldown-cmark to handle parsing Markdown and re-emitting it as HTML. As a result most of the work was in implementing the plumbing required to bridge the gap between, "I can convert Markdown text to raw un-styled HTML" and an actually usable tool which is recognizable as a blog generator. This includes handling command line arguments, traversing an input directory, recognizing metadata annotations in the Markdown, splicing in a header/footer and css, some basic non-syntactically-aware HTML templating for blog entries in the post list, generating an RSS feed, ect.
What I've ended up with is not a very robust or complete solution. That's okay though, because it does what I need it to do. Nothing more, nothing less. There is something beautiful about that. Case in point is a special feature that likely no other blog generator supports.
As of writing this I am about 2/3rd the way through a batch at the Recurse Center, a diverse community of developers with the common ideal of learning. In the Recurse Zulip instance is a stream where a bot watches a list of RSS feeds for new blog posts from Recurser and posts a link for each new blog post. Naturally if I am blogging about something that I think is technically interesting I would like for it to be picked up. That said, I also plan on posting things which would be more off-topic for such an aggregation.
As a result I would like to have a primary RSS feed which contains all posts and a secondary RSS feed containing only the posts which I deem applicable to be shared with the Recurse community in such a direct way. I was able to implement this via a metadata annotation in each blog post. Each post uses HTML comments in a specific format to specify a set of metadata for the blog generator to use.
<!--title: My Super Fancy Title-->
<!--description: What a super duper awesome post description.-->
<!--author: ForLoveOfCats-->
<!--date: 14 Jul 2021 11:00:00 +0000-->
I'm then able to extract this information by sticking my own code into the Markdown process. Have I mentioned how excellent pulldown-cmark is? So solving this was as easy as adding another annotation and using that to drive the generation of extra RSS feeds.
<!--additional-feed: recurse-->
And just like that I was able to tailor my own tool to specifically match my own usage case.
As I've said I intend to dump things here fairly often. If you found any of the above interesting there's an RSS feed on the main page and I will also share every post on Twitter. So until next time, cheers :)