Moving from Jekyll to a headless WordPress site

For the last – oooooh – nine years I’ve used Jekyll to create this website, either hooking it up to Netlify or, for the last few months, uploading the contents of the _site folder to some traditional LAMP hosting from the excellent Mythic Beasts. It’s like 2008 round here.

Well, nearly. Back then I used WordPress and, oddly enough, I’ve been thinking of reverting for quite a while. Why? Well, there are a number of push and pull factors, which I’ll take you through. Then I’ll tell you how I set up WordPress in a way that nearly meets all my requirements.

I don’t like writing how-to posts, so apologies if I don’t explain everything in detail, or step by step. The assumed audience is anyone who can set up their own website and has some experience of creating themes for a static site generator (it doesn’t have to be Jekyll).

What’s wrong with Jekyll?

Not much. It’s well established software. Its templating language Liquid is easy to use and flexible. Jekyll helps you build fast, cheap to run, stable websites that look the way you want them to.

However, for me it has three major problems. Firstly, it’s built on Ruby (which is fine in and of itself), but that does create dependencies on a bunch of gems, which in turn might require a specific version of Ruby. There is Bundler for managing all this, but over time it has become more work. I am not enough of a programmer to bother with this.

Secondly, I need Jekyll installed on my PC in order to build the website. I won’t be posting from my work laptop or my phone, for that matter.

Similarly, the third main problem is common to a lot of static site generators. Getting a post out there on the internet is a pain. Here was my Jekyll process:

  1. Open a new text file
  2. Add YAML data
  3. Write the post
  4. Open the site in the command line
  5. Create a new working branch
  6. Save the file
  7. Build the site
  8. Edit
  9. Open an FTP program
  10. Upload the contents of the _site folder to my hosting
  11. Merge the file into the main branch
  12. Push the main branch to Github

Now, I know there are quicker ways to do this. When I used Netlify you could skip steps 9 and 10, and there are services like Tina which offer a CMS and publishing to Github. But I don’t want to use VC-funded companies like Netlify, and Tina has its own set of Node dependencies. I’m trying to build something independent and free from the enshittifying web.

Why WordPress?

WordPress (or any other traditional, self-hosted CMS) solves the second problem. You login to your site – from your phone, even – type your post and press publish. Done.

WordPress partly solves the dependency problem. WordPress itself is easy to update, but if you’re using plugins, you’re relying on them being updated so they work with the latest verison.

WordPress also offers lots of secondary benefits. Unlike Jekyll, it’ll automatically create tag, category, author and date archives for you. Doing this in Jekyll is a PITA. There’s a really good indieweb plugin, which will handle outgoing and incoming webmentions, backlinks and comments and syndication to social media.

You could even enable comments.

Why not WordPress?

I don’t like the Gutenberg block editor, or block editors in general – give me a set of form fields to complete any day.

In my experience, WordPress can be quite slow, espcially if you’re not using caching plugins, which in turn can cause a whole range of dependency and technical problems. The combination of MySQL, PHP and its popularity mean you also have to protect your site from hackers – probably by installing yet more plugins.

The plugin ecosystem can be frustrating. Plugin authors want paying (fair enough, of course), but they’ll often release free versions that don’t do quite enough and then stick a big subscription fee on a “pro” version. A better approach would be to provide free, near-fully featured versions for hobbyists, and charge agencies and companies.

Finally, WordPress theming is complicated compared to Jekyll. In a templating language like Liquid, you’ll use simple syntax like for post in posts to loop through your site’s posts, and dot notation to retreive bits of post data, such as post.title. In WordPress you’re using a weird hybrid of templating and PHP that mashes your logic and frontend together, making it hard to generate the HTML you want.

Importing your posts from Jekyll into WordPress

This could be a separate post, but here’s an overview of what I did:

  1. Set up a WordPress install
  2. Installed the WP All Import plugin
  3. In Jekyll, created an XML file that contained all my Jekyll posts along with data such as categories and tags
  4. Used the WP All Import plugin to import the XML file into my new WordPress site, mapping XML nodes to WordPress fields, such as title, tags and the publication date
  5. Uploaded my Jekyll assets folder directly to my hosting so images didn’t break

This worked surprisingly well, but it did take some wrangling to get img tags to output usable attributes such as alt properly. I’d strongly advise testing with, say, just 20 posts before you do the full import.

I came up with a system that solves most WordPress problems

Speed and security

You’re reading this article on a static site, so it’s more or less unhackable and scores 100s on a PageSpeed test. But I wrote it on a subdomain that has a full WordPress LAMP install, in an editor. Once I’ve finished writing a post and it’s ready for publication on thisdaysportion.com, I use the Simply Static plugin to generate the whole site statically and deploy it to the main website.

I don’t need to use the Pro version as the freebie lets me either download a zip of the whole site, or publish it directly via FTP from the subdomain to main domain – remember, I‘m using traditional hosting rather than Github and Netlify. It is a cool system, but it does have the normal WordPress freebie plugin problem. Only the Pro version let’s you publish your new post’s static files and assets; with the free version, I have to republish the whole site every time. It takes 30-35 minutes.

There are other “headless” plugins out there, but none of them offer FTP publishing for free.

I guess my actual Wordpress install could get hacked, so I’ve installed a set of plugins that protect it, along with Updraft Plus for backups.

Not using Gutenberg

I’m not the only one with a downer on Gutenberg. Install ClassicPress for that not-so-bad, traditional editing experience.

Liquid-like templating

There’s a plugin for everything. Timber brings Twig – a PHP templating language that’s similar to Liquid – to WordPress, and separates the logical stuff you’d find in templates like single.php and page.php from the frontend. Instead, you edit files such as single.twig and page.twig, and these more or less look and behave like Jekyll layout files. (Thanks to Thom for the tip-off.) This means I get more control over the HTML WordPress outputs without having to grapple with PHP, or worry about escaping things properly.

So is it any better than Jekyll?

Sort of. It is good being able to visit a URL, login and start writing a post on any PC, or even a phone, and then be able to pick it up later on any other PC. To add a new tag to the site, I just enter its name into a box and click “add”. On the whole, editing is easier; for example, uploading an image rather than using an include is a far more friction-free experience.

Also, some WordPress plugins are really helpful: Smush handles image compression and lazy loading without me having to lift a finger. WP YouTube Light converts YouTube embeds to components that won‘t automatically track your visitors or make them download MBs of code when they load the page.

But there are some frustrations. Timber is good, but not as flexible as Jekyll layouts. I can’t get it to add a class (or better still, aria-current="page") to the current page link. There doesn‘t appear to be a page object, so I can’t use logic like if this page is a note then do so and so.

WordPress is WordPress. It’s overkill for my needs. Your posts are stored in a database rather than as a set of (im)portable text files. The latest Timber plugin isn’t a plugin – you have to install it with Composer. Plugin generated HTML can be inaccessible. The post editor isn’t that good. And so on.

You’ll never find what exactly you want

Those of us on the CMS journey know this. Do we even know what we want? I think I do:

Four and a half out of seven isn’t too bad. But whether I stick with this, I don’t know. I could even go full WordPress and just have a normal install that would accept comments. Or I could circle back to Jekyll. We’ll see.