Just want to do it? Skip to the Jekyll setup tutorial.

I ran my blog off WordPress for six years. There’s a reason it powers 30% of the web: if you don’t want to touch the Terminal or edit languages of any kind, it’s the fastest and most user-friendly way to create a pretty blog.

But WordPress is heavy. For a simple blog, detectable load times aren’t really excusable. If you want any kind of meaningful customization, you need to either pay for plans or go to the trouble of installing Wordpress onto your own server.

And if you’re going to bother with all that, you might as well use Jekyll.

Moving from WordPress to Jekyll is like switching from Nespresso to pourovers. Seems like more work at first, but you get complete control and better results with very little equipment.

Jekyll is a static site generator

Jekyll runs on Ruby. Gatsby is another popular example1 of a static site generator which runs on React and Node.js. They’re both similar ideas:

  • Type some content
  • Run Jekyll/Gatsby to generate static pages from that content
  • Upload these static pages to a server, or otherwise deploy the content.

Any time you need to make a change, you just repeat the process.

Why static pages over CMS? Total control + fast load-times

With static site generators, you get total control and super fast load times, with the CMS-like ability to write content in (almost) plain text.

When I was little, I found a neat HTML book in the tech section of the library and wrote a website from scratch in Notepad. While this was a great learning experience at the age of 7, it was completely impractical for any kind of real blogging. I’d have to manually update all the menus. I couldn’t have a dynamic listing of all my recent posts on the front page. I’d have to hand-format each of the blog posts. Real PITA.

People like content management systems (CMS) such as WordPress because they do away with all that trouble. Once you select a theme for your blog, you can just start typing out plaintext content. When you hit “Publish”, they are transformed into pretty posts which magically get pushed to your front page and are neatly sorted by date and category. Until, of course, you decide you want more customization, and then the whole thing starts to feel like dancing in a body cast.

Enter static site generators: the best of both worlds.

Jekyll allows you to write a post in Markdown, which is a very simple formatting language that you can learn in 5 minutes (seriously!). The added benefit with Jekyll is that you can throw in HTML when you need it (i.e. for things like superscripts, or links that target a new window/tab).

Once your posts are written, you run

bundle exec jekyll build

in the directory of your site, and Jekyll will generate your entire site structure into static HTML pages. You can review these offline at localhost:4000 and make any necessary edits.

When ready for publishing, you upload these static pages to your server, via FTP, scp, or whatever other method you prefer. You can even write yourself a nice shell script or “Rakefile” (Ruby’s version of the MAKEFILE) to automate this process. And Jekyll integrates nicely with all kinds of other deployment solutions that I haven’t yet explored.

Enough already, how do I set up one of these Jekyll static blogs?

Jekyll’s home page has good quickstart documentation. If you want a little more detail, I’ve also written a guide here.


1What about Gatsby?

I actually gave Gatsby a try as it came more highly recommended than Jekyll, but got stuck on this issue here. I tried all suggested resolutions in the thread and gave up after a few hours. Jekyll, on the other hand, was actually up and running in seconds. YMMV - if you have a suggested resolution for the problem above, let me know!