Perhaps it’s not strange that I’ve simplified the underlying setup used for blogging here, where “simplifying” is the strangest choice of words.
Starting with WordPress
There’s always been ideas floating in my head that I wanted to write down. There’s a gap between just taking notes (for yourself, if that) and publishing them in a reasonable format.
For about a year now, that format was that of a simple and straightforward WordPress blog. The blog is hosted on my uberspace, among other things: my Tiny Tiny RSS, a few slides made with reveal.js, and a handful of static files. None of this, mind you, is inherently publicly accessible.
Interactivity isn’t necessarily a feature
There is - or used to be - a directory containing the entire WordPress installation, which solely exists for the purpose of generating what amounts to a static site, using a slightly modified copy of WordPress’ default twentytwenty theme. If anything, that theme is bold in its typography and layout choices, and with a few tweaks visually pleasant.
This is done for two things I’d call implementation details:
- WordPress itself seems to have a notable loading delay. This hasn’t gone away after setting the scheduled jobs up be triggered by a cronjob instead of on loading the site. The whole process seems to work - as I get email notifications about successful updates at fairly specific times.
- I’m unsure if, after all these years of being criticized for it, WordPress nowadays has a better security story. For the longest time my ISP provided me with the same IPv4 address, but this stopped somewhere last year, making
.htaccessbased rules less useful to restrict
- There’s of course a slight difference between me visiting this blog vs. any normal visitor: I know when content updates and I set up email notifications for comments and the like.
The divide between Notes, Drafts and Posts
And while this worked, it also invited a large content divide: There’s the local notes that ended up written in Markdown, and the blog with the bundled WordPress editor. And by now I have amassed more drafts than actual blog posts.
WordPress wasn’t the wrong choice at the time, everything considered: If anything, it did a few things:
There’s no minimum requirement to create notes: If I found something interesting for my personal work, then that sounds like it’d make sense to share in one way or the other.
I have no deep understanding of most if not all topics, and opinions to the ones I vaguely understand. I do believe in debates being helpful if not to convince, then at least to enlighten me as to why people think differently.
I didn’t plan out much of a structure, and much of the key takeaways for writing - both notes and blog posts - has come from how other people do it. That includes coworkers, naturally.
It helped me look more deeply into topics that I wanted to explore, and actually did, but never spent the time on to properly write out in a way that helps others understand. Some of the things I did work at my day job made it into the blog - such as the short JUnit 5 Extension series, which in turn helped both me and others to understand why I made certain design decisions when creating a few.
My writing style does depend on the target audience in perhaps strange if not unexpected ways. This at least feels like it should raise the barrier to transition a piece of work between different stages, but more often than not it seems to make said transition impossible.
As much as I’d want to and do use it in notes, sarcasm and cursing rarely makes for readable content. While I’ve tried to filter the latter out of published content, I can’t say I’ve put much thought on the sarcasm side. And I’m not sure I will, either.
Quite frankly, a bit of humor and tongue-in-cheek remarks are major reasons for me to enjoy old content, but I’m torn if they’re inherently valuable.
Footnotes are the extended commentary track to include less serious moments, and while I would say their impact is hard to judge I could at least personally see myself moving this extended commentary somewhere else -
<!-- inline comments --> would never be rendered to be seen here, for instance.
While I had no fixed preconception of what I wanted a basic blog post to be like, most look fairly similar in structure: Header, cover image, content, key takeaways.
Although I often browse through HN and smaller aggregators, much of that was ephemeral: While relevant for a while, it ended up in an awkward part of my brain – the one that gets vacuumed about once a week. Hacking together a reading list of what I personally considered worthwhile was a unique take, but I’m not yet convinced it makes for good content across the content divide. I similarly tossed about three reading lists together in my personal Confluence space at my previous employer, and their inherent value would have benefited from a well-structured, long-term approach.
How do I actually want to write?
Minimally, I’d want to keep writing notes in Markdown, for which I’m currently using Obsidian, though I’m unsure if that’s standard-compliant.
So far, this is written with a touch of more commonly supported markdown, such as using normal links instead of Obsidian’s
[[file name]] wiki-styled links.
But here’s the part where this gets less intuitive: This is intended to be contained in a git repository where, at its core, I store all notes and whatever builds upon it, hopeful that I can reasonably use it as a place to aggregate relevant knowledge that goes into writing a blog post.
Conceptually, that’s close to a #Digital-Garden, explained well in Anne-Laure Le Cunff’s You and your mind garden and Maggie Appleton’s A Brief History & Ethos of the Digital Garden.
It’s great that it very much centers on creating a low-friction approach to writing. There’s only a slight problem: This isn’t where I want to go, because this isn’t what I had in mind for this site, and I still don’t. This site isn’t centered around my identity. If it were, it’d be on my personal domain - and conceptually not a blog. Is artificially limiting the selection of topics - or making them relevant to Software Engineering - even a good criteria for what to publish? For this blog: Yes. For my collection of notes in general: No.
Perhaps I’m too much of an introvert, for others openly peeking into my notes seems less than appealing even if I’m fine with talking about them in person.
Static Site Generators
Once upon a time - during university, to be precise - I actually had thrown together a fairly minimal Jekyll-based site to be hosted on GitHub (now long gone, for better).
I looked up a few generators, to see if they’d fit my criteria. Realistically, there’s three options that came into closer consideration and that I’ve tried for a few days each: Jekyll, Hugo and Zola.
Getting 90% of the way out of the box
And quite frankly, Zola is about the closest to what I actually want to achieve, but misses about a few points for what I want the final result to look like. With how my notes are laid out, I would at least need…
- a pre-processor of sorts to filter the relevant entries that should be published, as well as pre-rewrite some content to match regular markdown
- a post-processor to shift headings from
<h2>, and to optionally strip some system tags (i.e. which of the blog posts get published)
The remaining 10%
If I want to replace
#tags that are in the text with their name - mostly so that I get the benefit of connecting things up, but the public view is limited to the subset in the front matter, how’d I do that? Alternatively: If I want to continue using inline tags (not just in the front matter), how do I (a) present them as a site and (b) filter these tags, since some - such as
#todo make no sense publicly? That seems like a fairly low-level requirement of the Markdown parser, which somewhat excludes every option for that’s not often tweaked, presumably.
And if I want to support inline footnotes - which I’m using both on WordPress as well as within my Obsidian notes, how would I support that? Obsidian supports a custom shortcode for that, but that’s far from standard markdown, making it a rather important requirement to adjust markdown parsing some way.
So that’s where I have no insight to go on - as this was essentially written after having tested the generators mentioned above, but reached no final conclusion. Though with how straightforward I’m hoping it would be, I’ll go into more detail of how my static site is built in the next part.
- On a consumer broadband connection, I certainly had about no assumptions of having the same IPv4 address for years. ↩
- I now switched to having
.htaccessfiles limiting access by user for things that aren’t this blog’s admin panel, which is awkward. ↩
- Though as argued before, not all opinions are equal, and sometimes the most convinced person can sabotage a project. ↩
- In the era before Covid, you could casually look over someone’s desk to see they had built a Wiki-like system in HTML. ↩
- At night, I’m obviously Batman. Would it have helped if I watched any of the Batman movies? ↩
- This is really, really, really hard if you work with a change-resistant environment where the road to hell is, indeed, paved with good intentions. ↩
- Not all of the images chosen for articles make inherent sense, and I’d argue some are only very abstractly related when compared to the post they’re for. It is unfortunate that Unsplash has been acquired by Getty Images, and I can only hope that they’ll stay a useful resource in the future. ↩
- At the time of writing this part, this article contains a handful of
#todo, which I can see in the tag view. ↩