Mothballing a mudball (or, how I moved from custom software to Jekyll)

22 February 2019

In 2014 I gave up on Wordpress and, in the height of my PHP-hacking phase, decided to build some custom blog software with these design goals:

1. Lets me write in Markdown
2. Lets me upload from anywhere with FTP
3. Lets me “bump” posts to the top of the post list by updating them

Static site generators (SSGs) like Jekyll were already a thing. But I was still scared at the time by the git deploy flow, and I reckoned that I knew best that dynamic behaviour like that in PHP was important.

I built Upblog, and in its nearly-five year tenure, I wrote about 130 posts (generally averaging ten days between posts). It was easy to blog because the workflow matched the way I wanted to work. So design goals 1 and 2 turned out to be important to me.

Design goal 3, on the other hand, turned out to be pointless. I didn’t find I wanted it or needed it and so the software and I both forgot about it 🙂

Problems

Upblog had emerging problems, particularly performance and security. Version 1 of the software would parse every blog post (from source markdown) for every visitor! As soon as there were 10 posts or so, this became a huge problem, so I introduced a cache for metadata like post title, snippet, and link. The cache was rebuilt when I hit a special ‘/load.php’ endpoint, adding a (small) extra step to my deployment process.

When I got to 100 posts or so, the main page of the blog (a list of all posts) became slow. I refactored it to use AJAX to load the post summaries (as an HTML partial view) so that the page would come up right away, with posts a couple of seconds later.

Then I wanted to feature a few posts on the frontpage of my site using a slightly different view of the data, so I had to introduce a JSON endpoint in addition to the existing HTML partial view.

…All of these development tasks were driven by the design and complexity of the original software, rather than by genuine feature need. Now, Upblog was no longer helping me; it was hindering me. My baby had grown up into a mudball.

As for security, because of the infrastructure of my PHP shared hosting - no shell access, and separated from my domain name host - it was difficult to add HTTPS with LetsEncrypt. So I was stuck with HTTP, and that needed to change.

In the meantime, I’d used Jekyll to launch sites for work, for church, and for small projects, and my fear-factor for SSGs and git in general had disappeared.

Migrating

Upblog posts were raw markdown with no frontmatter. When the site compiled them, it produced a JSON file of metadata (like post date). These two files together told you everything about the post. I wrote a C# script to migrate each pair of files into a Jekyll markdown file; it essentially just introduced a ‘yyyy-MM-dd’ date into the front of each file name. Still no frontmatter.

From here, it was easy to rework my PHP templates’ require syntax to use Liquid include instead. I found Jekyll plugin Ruby Gems which did date arithmetic similar to what Upblog had done, and others to remove the need for most config:

plugins:
  - jekyll-optional-front-matter
  - jekyll-default-layout
  - jekyll-feed
  - jekyll-timeago
  - jekyll-titles-from-headings

GitHub Pages vs Netlify

I didn’t realise at first that you can’t run “any old plugin” on GitHub Pages (GHP). GHP is an intentionally limited platform, expected to compile fairly vanilla sites. They don’t want to run arbitrary Ruby code on there, and I get it.

Netlify, in contrast, is a more fully-featured container…izer… giving you the liberty to compile whatever the heck you want. So I moved my build process there. I just used the web interface (not the CLI) to set up, and it wasn’t hard.

Legacy and Redirects

I am keen to never break a link. The best URLs are the ones that never change. But I knew that if I pointed https://stegriff.co.uk to my Netlify site, it would break a lot of links to old content on my PHP server. The site goes back much further than the Upblog era, with plenty of externally-linked content dating back as far as 2008. So I have a two step plan:

1. Leave the old server up at files.stegriff.co.uk and try to give visitors helpful 404 pages which get them back on track to the right resource, and
2. Gradually migrate frequently-accessed content to the Netlify site

But this introduced a new risk; having two copies of my blog online. Doing that would wreck SEO and also provide a confusing visitor experience (I’d applied a new style to the new version)

As a result, I hamstrung the Upblog software’s index.php (the file responsible for handling all requests and redirecting you to a rendered post), replacing it with a clever redirect to the corresponding post on the new site. Any non-post requests just go to the stegriff index page.

There were a few other things to tweak, like the netlify _redirects file, and some DNS-level stuff. With config in so many places, I knew I needed documentation, so I wrote an infrastructure.md file in my website repo which tells future Ste anything he needs to know!

Outcomes

Outcomes have been great:

• I’m on HTTPS
• Deployment is actually easier than ever (git is pretty much as ubiquitous as FTP, plus no more /load.php step)
• It’s easier to add new features
• Site speed has increased enormously (static HTML is much faster than a ponderous PHP script!)

There were other small wins, like removing jQuery as a dependency, because I no longer load front page posts via AJAX.

Lessons

• Do try to find a blogging system that fits your mind
• Do invest the time in giving existing systems the benefit of the doubt, and trying them out
• Don’t reinvent the wheel!
• Do pause, analyse, and calibrate your choices when possible

As this post is syndicated on dev.to, I wonder what you think? If you’ve been through a similar journey, link your story in the comments. Have you ever declared URL bankruptcy and just broken every link on your website? What do you think of Netlify and Jekyll?

Thanks for reading my long story!