loading...
Cover image for Mothballing a mudball (or, how I moved from custom software to Jekyll)

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

stegriff profile image Stephen Griffiths Originally published at stegriff.co.uk ・5 min read

Original at https://stegriff.co.uk/upblog/mothballing-a-mudball/

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.

Bart makes a muddy snowman using snow from under the car

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.

Pairs of markdown and JSON files in Filezilla

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

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)

Michael Scott shouting, I Declare Bankruptcy

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

Green lock icon in address bar

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!

Original at https://stegriff.co.uk/upblog/mothballing-a-mudball/

Posted on by:

stegriff profile

Stephen Griffiths

@stegriff

Aspiring Jesus follower; successful nerd. Pro full-stack developer 8+ years, rapid prototypes for fun.

Discussion

pic
Editor guide
 

First, awesome website. I will borrow the option to choose light or dark mode from you... Nifty.

Netlify + static site generator + netlify cms I think is an even better combination because I like editing on the go.

My only problem is that netlify cms keeps crashing on mobile browsers, yet I chose it so I don't have to be on my computer to post or update content.

Have you tried netlify cms? If so, what are your thoughts about it?

 

Thanks Mike! I haven't looked at Netlify CMS yet so I have no thoughts. If it "just works" with whatever SSG you're working with then that's pretty cool. I'll have to check it out sometime. I still need to store users' light/dark mode setting to localstorage... all in time! Cheers

 

I'm using netlify + GatsbyJS + netlify cms on my new blog.

Jekyll has always been my first choice though. I'm still comparing the various SSGs.