brainwagon

Back on May 2, 2024, I was aboard a plane heading toward a real vacation: ten days spent on a cruise and visiting friends and family in Florida. While on the plane, I jotted these notes in Markdown, detailing some of the reasons why I was considering switching my blog (now past twenty years old) into a site which was generated by a static site generator. Shortly after this trip, I was laid off from my job at Pixar Animation Studios, and so I haven’t been back to revisit my thinking. But in rereading this for the first time since I wrote it, I think I had obviously done some thinking about it, and it was helpful to bootstrap additional pondering. Without further comment, here are the notes as I crafted them back then…

Notes taken while on a plane…

As we speak, I’m sitting in the very cushy “MINT” level seat on a Jet Blue flight, hurtling across the United States on my way from SFO to TPA by way of JFK. My wife Carmen bought me this special seat because I’m at the start of a ten day vacation in celebration of my 60th birthday. This trip includes visit with my son and his family, a cruise out of Port Canaveral, and some time at DisneyWorld. Truly, it should be a great trip.

Since I have this (very cushy) seat, with plenty of room, I’m actually able to comfortably use my laptop. Toward that end, I’ve decided to try to learn a bit more about static site generators. I’m aware of three or four utilities that serve the purpose.

1. mkdocs — written in Python (which is a plus)
2. Jekyll — which is written in JavaScript, and is probably the most popular open source solution of its type
3. hugo — which is written in Go, and which I decided to try to give a whirl

Luckily, this flight has (pretty good) wifi, and I was able to use apt to download and install the necessary bits of software and get it running.

During my bout with COVID-19, I had some time to sit and think about my dormant blog, brainwagon.org. A couple of things have things came to mind.

I really don’t care much for WordPress

I haven’t been doing necessary maintenance on my blog, and as the result a couple of times during the last six months, it has gone off line, once requiring me to contact my ISP to get an upgrade of PHP that happened and caused it to bork because of a misconfigured plugin. Even remembering how to log into my server and dork around with this stuff seemed more complicated than I would have hoped.

The reality is that the total of text that I’ve written over the years is just around 20Mbytes, almost all of it written by me. While I suspect that during it’s heyday I may have had a modest number of regular readers, it never really formed a community. The overwhelming majority of comment traffic that I got on the blog was frankly comment spam. In fact, were it not for the combination of comment spam and the performance tax that running a complex database system fueled by one of the worst programming languages ever created, I suspect that I could run my blog entirely on a little Raspberry Pi Zero and a 4Gb microSD card, hosted very nearly anywhere on the planet.

I’ve known this for a while. So… the question is why don’t I just do that?

That’s what this experimentation with hugo and other static site generators is all about.

Exporting the WordPress blog

Nevertheless, I didn’t want to lose my entire history of writing. While I didn’t think that losing the ability
of others to comment on my blog was necessary, I did want to continue to have a representation of some of the early work and exploration that I’ve done over my decades online. This meant being able to export the mass of WordPress XML into a more portable Markdown syntax, so I could integrate it into another static site generator.

The plugin wordpress-export-to-markdown by lonekorean seemed to be just the thing. It took the XML dump of my WordPress blog and carefully reconstructed some quite reasonable looking markdown as well as downloading all the linked images that I had. The result was about 600Mbytes that distilled my online musing over the past few years.

One thing I did notice was that many of my image links were in fact broken. I had moved my blog a couple of times over the years, and it seems likely that at some point in the past I failed to properly move the images subdirectory and had lost a lot of early images. It remains to be seen whether the Wayback Machine may have cached some of this content and might be able to recover some of this, but that is the task for another day.

The brainwagon wiki

I briefly dabbled with using DokuWiki as part of brainwagon. All the complaints that I had re: the brittleness of PHP and overkill that I lodged against WordPress could be equally lodged against DokuWiki. I wanted a relatively simple place that I could arrange and organize various bits of information and links to other places on the web, but DokuWiki seemed to be another order of magnitude more complicated than I wanted. But it did have a number of useful features:

I generally liked the notion of using Markdown. I’m seriously old school. Around 40 years ago, I got my first
Unix account on a machine at the University of Oregon, and learned how to use the screen editor vi. Since then, I’ve seen editors come and go, but frankly I’ve never found that their enhanced capabilities were significant enough to make me wish to adopt them. The fifteen or so commands that I understand how to use in vi make editing text both fast and efficient, as long as the subject matter you are editing is more or less basic ASCII text. This reinforces the use of Markdown as the source language. You can concentrate on what you are writing, and leave “how it will look” decisions for later.

When I actually looked at the sum total of links that I had stashed in DokuWiki, it appears that the amount is actually pretty limited. Converting them over to markdown sufficient to integrate with Hugo even by hand should present no more than 15-20 minutes of work.

I don’t like WordPress Part II

There is another reason that I don’t much care for WordPress. It’s kind of shitty for people like myself who
use the nominally “free” version. In the time I’ve been on the web and nominally blogging, WordPress has gone from a basic open source blogging platform to big business. And since it is big business, it makes a lot of decisions about how to maximize value for the owners of the system, and relatively little time looking out for the little guy, or even asking themselves whether the decisions they are making is actually making the platform better for anyone. Decisions are made on the basis of whether a given change is more likely to cause someone using the free tier to the premium tier. Unfortunately, one of the ways that you can do that is to actually break the free tier. It is a vastly easier method to get people to send you money than to deliver consistent, reliable software at the free tier, and worthwhile, thoughtful additions to the premium tier.

I can hear some of you out there saying “but aren’t the free tier users just freeloaders?”.

No. No. No.

WordPress began as an open source project. This means that people contributed their work to the project with the hope of making a better blogging platform for others to use. But somewhere along the way, it somebody began to notice that people would actually pay money for a blogging platform. And look, here is a platform which has begun to be popular, so a company formed around it. That didn’t seem bad. In fact, I thought that the involvement of companies in sponsoring and shepherding open source seemed like a profoundly good thing to me for years.

But it’s clear I was mistaken. Recently Jeff Geerling wrote a thoughtful argument on this subject:

Corporate Open Source is Dead — Jeff Geerling

This strategy has a name: the rugpull.

It is known by another name which might be more familiar: the bait and switch.

It basically consists of the following:

• Find an open source project that has an active community for a project which people find of value.
• Build a product using that open source code base.
• Accept new, important modifications under a “Contributor License Agreement” (CLA). After all, who wouldn’t want to contribute to a growing and useful open source project?
• But CLAs aren’t open source. They exist only to subvert open source licenses by having you sign your rights away.
• That’s the rug. Then, at some point when the corporate master wants make more money, they pull the rug out from you. The source code that contributors have been adding to the project to create value for users of the system is suddenly squirreled away from free access, and its only people in some paid tier who suddenly can access the code.

Somebody in this scheme is subverting the ideals of the original project, but it’s not the people who are using the software for free. That is, after all, the original point of making open source in the first place. It is the corporations who are the freeloaders in this scenario: harvesting the work of individuals and communities to reap privatized profits.

Okay, that was an aside, back to my simple blog…

Back to static site generators.

Well, perhaps.

But I can’t help but think that the layers upon layers of stuff that are piled up over the year has resulted in a kind of diffusion of content. The total size of the software that is used to maintain my modest 600Mb of content is vastly larger than content itself. To make even modest changes to WordPress or even wordpress themes requires significant knowledge in a bunch of domains, such as

• knowledge of php
• knowledge of SQL
• knowledge of JavaScript

I know a little about almost all of these things, but none of them are my day job, and none of them have anything to do with the content that I’m interested in producing for my blog.

This is why static site generators appeal to me:

• In general, they don’t rely on making your content “Turing Complete”. Your data is data, and data is usually simpler to deal with than programs.
• The total size of the toolset used to generate sites is quite small. The compiled package for hugo is just 21Mbytes, and consists of a single executable, without any auxillary data files.
• If you wish to do version control, you can use conventional tools which are familiar to software developers like git. While it seems a bit odd to complain that WordPress relies on a bunch of knowledge of tech, and then list using git for source control is a positive for hugo,
  
  I would submit that knowledge of source code control is a vastly more portable skill, and the simple fact is that there is nothing all that special about git. If you have knowledge of a particular source code control system, you can go head an use that. Over the years, I’ve used sccs, RCS, CVS, hg, perforce and git, and probably others that I’ve entirely forgotten. You could likely use any of those, or others if you wish. This is rather different than the use of php, SQL and JavaScript in WordPress.
• Yes, hugo is written in a language go, which is perhaps even less well known than php. But for the most part you don’t need to know anything about go to use hugo.
• The data format that forms the basis of hugo is Markdown. Markdown is just ASCII files, which are easy for humans to read, write and modify, with any tools that the writer finds convenient. It is also information dense: the author generally spends more characters writing about what they wish to write about, and less about what it looks like. Decisions about what something looks like are generally made in a separate place. This enhances portability and longevity of data. Once my blog was converted into markdown, it becomes relatively simple to move and modify: I had a first pass of this blog in just a few minutes, configured using a system I had never used before (hugo) in less than ten minutes while on an airplane and working on just four hours of sleep.
• The use of a database for this kind of application seems like it’s probably overkill. Using files and filesystems to organize data seems like a much better notion, and requires less overhead.
• If I wanted to move it to another system like mkdocs or Jekyl, it would likely take a similarly short period of time.
• Even if every static site generator in existence went the way of the dodo tomorrow, it’s likely that a small team could write a generator that could read in my data and generate a new website could be written from scratch in just a few hours of work. Such a system wouldn’t be as feature rich or efficient as these generators, but it would be possible and much more straightforward than (say) writing something to ingest WordPress XML dumps.