The Jargon File, a compendium of hacker lore, defines “bit rot” as a jocular explanation for the degradation of a software program over time even if “nothing has changed”; the idea behind this is almost as if the bits that make up the program were subject to radioactive decay.
This post is a late-night rant that gives this new blog’s motivation and high-level details.
The story started four years ago when I built my Gatsby-based blog. It was based on a “minimalist” template, and the result was beautiful right out of the box.
To this day, 99.9% of my changes were to the blog content written in Markdown. I didn’t touch the codebase because I didn’t need anything else.
As the number of content grew, I noticed the build started to get slower. Well, this goes with the territory, and I didn’t care much as I could easily preview my changes in my code editor. Builds only need to run on Github actions, and I didn’t care how long that took.
Fast-forward to two days ago: the last straw was that after a year or two, I couldn’t build my blog locally anymore. I was hit with numerous warnings and errors every time I tried.
Why is this failing? Last I checked, Markdown, HTML, CSS, and Javascript haven’t changed significantly. My requirements from 4 years ago have stayed the same. So, what gives?
I decided to have a look behind the veil. Lo and behold! I found my blog has 1537 dependencies!!! Why do I need multicast-dns? Or any one of the other 1500 dependencies?
Bruv! I just want to write in Markdown and have it show up on the internet. I don’t want to be an “enterprise engineer” on a side project.
I was shouldering the maintenance burden of dependencies I didn’t actually need. This large surface area maximized my exposure to bit rot.
Let’s review my requirements from four years ago, which hasn’t changed:
I am confident these requirements will remain unchanged for the next 5 years. Therefore, I just need to find a tool that is resilient to bit rot. Unfortunately, most Markdown blogging tools are more complex than I need. They often offer features I don’t need or sacrifice simplicity for flexibility.
Fortunately, I stumbled upon this blog template. The last commit was five years ago (older than my blog), and when I pulled it, it worked locally without any hassle.
Parfait! According to the Lindy Effect, this tool should last another five years. Here’s how it functions:
It reads all the Markdown files in a src directory and converts them into HTML files in a dest directory. It comes with a simple CSS file in the dest directory for essential styling and uses the marked library for Markdown to HTML conversion, along with highlight.js for syntax highlighting.
It’s that simple! I think, this template was more resilient to bit rot because:
I decided to use this as the basis for my new blog with the following changes:
Katex.marked and highlight.js libraries to the latest versions. I committed my node_modules to the repository to keep the dependencies local.The build script consists of ~100 lines of pure JavaScript. It is so simple that I could rewrite it in an hour if needed.
I rely on standard features from Markdown, HTML, CSS, and Javascript, which will likely stay the same in the coming years. If any of my third-party dependencies rot, I can easily replace them with something else or choose not to update them.
I’m pleased with my new blog setup. It is simple, fast, and resilient to bit rot.
That starter pack or boilerplate template might help you start quickly, but it often conceals unnecessary complexity. You don’t need a rocket ship to go grocery shopping.
Time is precious! And I want to spend it on what truly matters to a product.
PS: I ruled out third-party services because I don't want to pay and because the interest of these services usually deviates from yours overtime (cough cough Medium). If GitHub changes something about Pages, I can easily move my static files elsewhere.