March 7, 2014

This post is the first in what I hope to be a weekly series of posts titled "pick of the week." In these posts I will pick something cool that I use or have used and describe why I like it and what I use it for. Any topic is fair game. They will probably be mostly apps or other geek tools that I've come to rely on.


This week's pick is Jekyll, a powerful tool for transforming plain text into websites and blogs. Jekyll was created by the guy that started GitHub. It is also the engine that powers GitHub Pages.

The back story

I ran across Jekyll because I was looking for a simple solution for creating a blog using Markdown. As soon as I found out about it, I tried it out. They have a guide for getting up and running in seconds. That is literally all it took. It was easy to to install and to create my first Jekyll project. I didn't fully wrap my head around it at first though. In fact, I tinkered for a few minutes and then forgot about it for a while.

What brought me back to Jekyll was this website. I've wanted to start a personal website and blog for a while now. I've tried all of the major content management systems and I'm not a huge fan of any of them. I've used WordPress extensively in the past. The most appealing platform to me out there is Squarespace. I love their simplicity, their layout engine, their beautifully designed templates and all of the other features they have. For just about any web project these days, my first recommendation would be Squarespace. However, I like to tinker. I like to pop open the source code and mess around. I like the ultimate flexibility of writing a website from scratch. To be fair, Squarespace does offer that. You can get a developer account and have ultimate control. In fact, I did exactly that with a website I developed for my brother's business Moby1 Trailers. For this website however, Squarespace posed one major problem, cost. I didn't want to pay for hosting.

With Squarespace out, I went searching for a platform with this criteria:

  • Allow me to blog in Markdown, and leave the blog posts in Markdown.
  • Give me ultimate control over the guts of the website, the HTML, CSS, etc.
  • Allow me to publish posts and updates to the site via Git.
  • Easy to export or archive my content.
  • Free.

Squarespace fit all of those criteria except for the last one. Arguably, Squarespace also has other advantages like their media management and layout engine. Jekyll appealed to the programmer inside me and the free part was the deal maker. In my search I also ran across a couple of cool blogging platforms that had a lot of appeal. I found and Svbtle which are both minimalistic blogging platforms. They both offer blogging in Markdown and have minimal customizability. I liked that aspect. There is beauty in simplicity and freedom in constraints. While each of those minimalistic blogging platforms were appealing, they didn't fit my critera.

What is Jekyll?

Jekyll is the un-content management system. Jekyll generates a static HTML website. You can choose to host that static website wherever you want. Any web server will do. What makes Jekyll powerful is that you can take advantage of templates so that you don't have to repeat the same HTML layout in every file in your static website. It is also "blog aware." The content management consists of editing text files. It is a simple and beautiful concept.

As a web programmer, I'm used to building websites using templates. Templates allow you to have common headers and footers on every page, only defined once and applied automatically to every page in your site. Jekyll's template system is built on the Liquid template engine. It looks similar to Django and Jinja2 which I use every day.

A Jekyll powered website begins life as a collection of HTML template files called layouts, a series of pages that just define the content and inherit the overall look and structure from the layouts, and a series of blog posts that are just pure Markdown and inherit their final look from the layouts.

All of these layouts, pages, and posts live on your local hard drive. Jekyll has a command for building the website, taking all of the pages and posts and applying the layout templates to each. The build process puts all of the generated content into a folder for you that you can then upload to your web host of choice. In addition, Jekyll has a built in web server so running jekyll serve launches a server running locally that allows you to preview what your site will look like. This is great for testing and developing. You know exactly how it will look before you publish it.

Publishing a Jekyll Site

There are two ways to publish a Jekyll powered website. The first is to just run jekyll build which compiles your site into a folder called _site. You take the contents of _site and upload it to your web server of choice. It is just static HTML.

The second way to publish a Jekyll powered website is to use GitHub Pages. I'll let you read the details, but in short, you set up a Git repository on GitHub and push your Jekyll project to that repository. GitHub does a jekyll build on their side and your website magically appears at

A Jekyll / GitHub Pages Workflow

So my Jekyll to GitHub pages workflow looks like this:

  • Edit and create pages and posts locally on my computer.
  • Use jekyll serve to view and test my website running locally on my computer.
  • Commit my changes locally using git.
  • Run git push origin master to push the latest version of my website to GitHub.
  • Within seconds, the jekyll build process takes place and the latest version of my website is visible to the world.


Jekyll appeals to the geek / programmer in me. I can tinker all I want. I like to try new things. For example, at the time this post was written, I used the Foundation responsive front end framework for the look and feel / structure of my website. Tomorrow if I want to switch to Bootstrap3, I can do that with minimal effort.

My website and blog are now future proof. My blog posts are just Markdown files sitting on my computer. They are just sitting there in plain text. I don't have to worry about being locked into any platform. I don't even have to worry about exporting my content from a web host. My blog posts stay in Markdown. I don't have to convert them to any other format.

As a bonus, I have built in file history tracking because it is hosted on GitHub. If you are curious, you can view this website in its GitHub repository form and see how a Jekyll powered website is structured. You can also browse through the commit history to see what I changed with each version of my website.