Migrating from WordPress to Jekyll

I recently decided to migrate my website from WordPress to a set of completely static pages, and settled on Jekyll for managing my site content. The whole process took a good few hours, but some of that time was spent on a little diversion where I took the opportunity to move from a front end workflow based on Grunt to Gulp.

What’s wrong with WordPress?

Nothing! WordPress is great, actually. It’s free, open source, and has a 60% market share of sites that are powered by a Content Management System (CMS), or an impressive 30% of the entire web, including sites that don’t run a CMS at all. It has a huge community of users and developers, and can be extended in any number of ways with its plugin system. I’ve built and maintained sites on WordPress for years, it’s just that I don’t personally need everything WordPress brings with it for this site.

The only thing keeping me using WordPress for my site was the nice user interface for writing posts and notes (a custom post type I set up for microblogging on my own domain). The only plugins I installed were Gravity Forms for a contact form, and iThemes Security for changing some default settings and securing the admin interface a little better. For the convenience of that interface I was making all the tradeoffs a CMS entails - third party code I had no control over, performance penalties, database connections, and generally a lot of power I wasn’t using.

Why Jekyll?

Jekyll was one of the first and remains one of the most popular static site generators, and the documentation is excellent so I set about converting my site’s current WordPress theme to static pages. Jekyll uses markdown for content editing which is convenient for me as I use it a lot already for note-taking, and it converts those markdown files in to static HTML files for you to upload to your webserver.

Converting my WordPress theme

Converting my WordPress page templates to static HTML files for Jekyll to insert content in to was pretty simple, and mostly consisted of replacing PHP code with Jekyll’s functions and loops. Pleasingly, I was able to replace a huge chunk of PHP dedicated to composing and outputting a list of post categories with a much smaller Jekyll snippet:

{ page.categories | array_to_sentence_string }

A lot of Jekyll’s syntax is like that - simple and easy to read.

Getting my posts out of WordPress and in to Jekyll

Jekyll’s documention has instructions for importing content from a number of other CMS, but I lost a good hour or so trying to use the WordPress importer script due to missing dependencies. I gradually found and installed them by running the script and responding to every failure by installing whatever dependency it complained about, but once they were all installed it still couldn’t connect to the MySQL database running on my local apache webserver. It was probably an issue with my apache setup, but I didn’t want to sink any more time in to troubleshooting.

Instead, I used Jekyll’s wordpress.com importer - it imports content from an .xml file you generate using the export tool in WordPress’ admin panel. I did one export for posts, and another for my notes custom post type. Once my notes were imported, I defined them as a collection in Jekyll’s config file.

Syntax highlighting

Several of my posts contain code snippets, and syntax highlighting makes code a lot easier to read. On my WordPress site I used a plugin to add highlighting to code snippets in my posts, but Jekyll has highlighting built in. All I had to do to style my code snippets was choose from a selection of themes and add the CSS to my build process.

Keeping the dev process fast

$ jekyll build, once I’d imported a few posts (and many notes), got a little slow as it rebuilds the entire _site/ directory from scratch every time a file is saved. To make development less frustrating, I spent a little while configuring Gulp to handle Sass processing so that I don’t have a long wait every time I save changes in a Sass file. With Gulp configured to watch Sass, JavaScript, and image files I have almost instant Browsersync refreshes, with the longer waits only when Jekyll rebuilds pages based on my changes to markdown files.

Conclusion

I’m really pleased with the migration from WordPress to Jekyll. I get to write my posts and pages in markdown and the output is a collection of simple HTML files I can $ scp up to my webserver in seconds. There are no CMS or plugin updates to worry about, no database to keep synced between the live site and my local dev environment, and my site has never been faster: