Migrating From WordPress to Jekyll -- Part 1

In part 1 of this article, I talk about why I moved my website from WordPress to Jekyll. In part 2, I go over how this is accomplished should you want to make the move yourself.

“Why do you make things hard for yourself?”

When I was maybe ten years old, my dad would take my brother and I on long walks through the woods. My dad loved the outdoors, and these walks were a cheap way to tire us kids out. I loved going off the beaten path and negotiating my way through the trees and brush. This was a lot slower, ducking under branches and dealing with snares. I’m sure my dad found this a little frustrating because he had a schedule to keep. He would ask me to come back to the path and I would refuse. I remember him exclaiming at some point, “I don’t understand why you have to make things hard for yourself.” I’m sure I said something like, “Because it’s fun!” Negotiating the bramble wasn’t as fast or easy as taking the path, but it was a lot more interesting.

Comparing WordPress and Jekyll

Wordpress (specifically the hosted service at WordPress.com) is powerful, easy to use, efficient, and even pleasant. A variety of themes and other customizations are available. You can update your site from any device with a web browser. You can use the visual WYSIWYG editor or edit HTML directly. It handles multiple authors and a variety of third-party plug-ins are available to provide various kinds of functionality.

Jekyll, on the other hand, is almost none of those things. Jekyll is essentially a document processor that runs on your local machine. It is very flexible and requires little in the way of resources to produce a quality, content-driven website. It also supports multiple authors and plug-ins, but not in the same way that WordPress does.

The key difference between these two options is that WordPress sites are dynamic and Jekyll sites are static. WordPress relies on a database to store data. Content is pulled from the database and assembled by the application after a request is received. This also means that your web server needs to have the resources available to retrieve and assemble a response for each request. Jekyll does all of its processing up front to create a set of static files that are ready to serve. This means that a Jekyll website doesn’t need a database or an application runtime (aside from a web server). Trading WordPress for Jekyll is trading ease-of-use for flexibility – polar opposites in the software world.

Advantages

It’s Cheap
Having a custom domain (like davebucklin.com, or serial-hobbyist.com) at WordPress.com is not free. I paid for domain registration at my registrar, but the privilege of using WordPress.com’s nameservers comes at a price. It’s not crazy expensive, but it’s not nothing, and I’ve been feeling frugal lately. I had three separate blogs, each with a custom domain. So, this move was going to save me some money. Hosting a static website on Amazon S3 is not free but, for a personal site, it can cost a lot less than what WordPress.com was charging me. GitHub Pages is a free hosting option for static sites and has the added benefit of using GitHub as a repository for your content.

Easy Authoring
I love to author in markdown. It allows me to use lightweight formatting to structure my writing without having to rely on proprietary or heavy formats. Markdown is editor agnostic, so I can write using anything that lets me edit text. Using WordPress, I would draft using markdown, and then use the Markdown Here extension for Chrome to convert markdown to HTML. (I use this all the time to create tables in Gmail.) This worked remarkably well, but the styles would not always translate consistently. This process also caused me to lose the original markdown in my draft. So, this move would extend the utility of markdown in my workstream and enable the end result to have consistent styles.

It’s Fun
Finally, I was looking for a solution that had more DIY appeal. WordPress is great, has lots of features, and is easy to use. For my purposes, it was overkill and ended up getting in the way as much as it helped. I wanted to be able to customize my workflow, add custom integrations and tools, and modify CSS directly. I wanted to do cool stuff. Being able to tweak my website is good, but Jekyll is capable of so much more. To see an example of this, check out Tom Johnson’s blog, I’d Rather Be Writing, where he sees markdown as a viable alternative to DITA, and has created his own documentation-centered theme for Jekyll.

Disadvantages

Saving money, authoring in markdown, and doing cool stuff. These are great advantages, but what are the downsides?

Hosting Complexity
The complexity of setting up hosting on AWS took some patience, but it’s a one-time set up and Amazon provides excellent step-by-step guides. I had to create an AWS account, create storage buckets in S3 that would store my static site, and set up DNS using Route53. Setting all of this up may be overkill if GitHub Pages provides what you need.

Workflow Complexity
When I make updates to my content, I have to use Jekyll to rebuild the site and then upload everything to S3. This ties my production process to a machine with Jekyll installed and all of my files available. I’m sure I could automate this by installing Jekyll on an EC2 instance and pulling posts from a cloud document storage solution like Google Drive, Box, or Dropbox. Using GitHub Pages, I would only need to be able to clone my repository and push my changes up to GitHub.

User Error
Using Jekyll, I have many more opportunities to make mistakes and break something. I could mis-type a configuration value, bork some CSS, or accidentally convert all non-numeric characters to backslashes while trying to get clever with regular expressions. Fixing your own mistakes is a great way to learn how something works. When you can find and fix someone else’s mistakes, you’re on the road to mastery. (Again, with GitHub Pages, I could revert my local copy to a previous state.)

Summary

WordPress will let you set it and forget it. If your website needs a database (e.g. because you need to authenticate users, or you have a store, or content is somehow conditional), you should consider WordPress (or Squarespace, or Wix). Jekyll is great if your needs are relatively basic, you want to do it yourself, tweak endlessly, and string solutions together in new and exciting ways. You can also look into Hekyll and Hugo. While you can make good use of Jekyll without understanding how it all works, you may get a lot more out of Jekyll by exploring How Jekyll Works.