Zero to Jekyll in 20 minutes

By Jonathan Jackson

Why Jekyll?

As a Rubyist you’ll often see example code that starts like rails new blog and it is tempting. Many of us have gone down that rabbit hole because, as a programmer, it feels right to start from scratch and have control of every little aspect. It’s your baby, and you want it to be perfect.

That isn’t important!

With few exceptions, writing your own web application for a blog is not only overkill but actually reduces your ability to produce content. In the end, you are creating a blog because you believe you have something to say, so say it. That’s what Jekyll does: it stays out of your way, giving you all the convenience of a custom application without having to waste all of your time in development.

I recently made the switch from Rails to Jekyll on my own blog. It’s been a rewarding experience and I think it might be right for you. First, let’s talk about what Jekyll is.

Jekyll is a blog-aware static website generator.

Essentially, it’s an engine that chews up your markdown and spits out a bunch of HTML pages in a _site directory so that you can serve it from your favorite webserver (Nginx/Apache). There is actually a lot more to it, but once you have the basic structure down, all you have to do is write the content and it will output a pretty website.

It uses Liquid[1] templating to allow more semantic organization within your site, as well as extensible helper methods. It also supports several markdown converters, so you can write in whatever flavor you prefer (i.e. Markdown, Textile, HTML, et al.)

Now that you are somewhat acquainted with Jekyll, we can dive straight into creating a blog.


The structure of a Jekyll site is somewhat flexible with a few required elements. There are a number of great sites listed on the Jekyll wiki[2] that offer some insight into what constitutes a Jekyll site. That said, we’ll be using @mojombo’s site as a reference, with a few modifications.

If you are going to follow along, run this:

Once you’ve done that you should have a tree that looks like the following (minus the posts).

This tree has all you need to get started producing content. Once you have your first post ready (clever name right?), you simply type:

Then navigate to http://localhost:4000/2012/03/27/your-first-post-in-markdown.html  and you’ll see your text magically displayed in HTML. Before this though, you have to ensure that each post you want parsed contains YAML front matter.

Inside your layout/default.html, just create the default HTML layout of your page and drop in your liquid tag for your content like so {{ content }}.

That’s it. You now have a Jekyll blog. We’ll get to publishing it in a minute.

Extending Jekyll with Ruby

First, let’s be clear… Ruby is awesome! Jekyll leverages the power of Ruby by allowing you to extend simply by dropping any .rb file into the _plugins directory [3]. For example, when I converted my blog from Ruby to Jekyll, I had a URL scheme that omitted the .html extension from all the URLs. Since I didn’t want any existing URLs to break, I needed to create a liquid tag that would allow me to strip it. It was this easy:

I simply open up Jekyll and add my own custom module to it. Then register_filter with the Liquid templating system and you’re off to the races. To use this just place {{ page_url | remove_extension }} wherever you need the stripped URL. Of course, Jekyll will still generate the files with .html extensions, so serving these URLs is something that you’ll have to configure with your web-server.

I don’t think I need to tell you how useful this is. Almost anything you need to do, you can build yourself. The most common reasons for creating a plugin are generating your HTML based off your own rules (Generators), creating a Liquid tag to alter/modify output (Tags), and filters like the example above. All of these things are as easy as above.

If you’re not that much of a coder, no big deal. There are a bunch of plugins available on the wiki and should be as simple to install as dropping them into your _plugins directory.


Alright, all of the work you’ve done so far doesn’t amount to much if you can’t serve your files to your audience. Have no fear, there are a number of ways to get your Jekyll blog to the public. Since Jekyll generates a _site directory with all associated assets/HTML, there isn’t much Jekyll-specific server configuration. Most of the settings are dictated by which web-server you use. For example, in Nginx the configuration for your blog would look like this:

Then just rsync your _site to /var/www/blog and you’re off and running.

However, if you’re a humble hacker on a budget and don’t want to have to host your own site you can use Heroku. Let’s do that.

Heroku & Jekyll Sittin’ in a Tree

The best technique is to use rack-jekyll to create a rack app out of your Jekyll site. It doesn’t require too much setup to work, and once it’s completed you can use Git as both your writing and deployment workflows.

The first thing needed is a rackup file:

Next up is the Gemfile which should look something like below. Be sure to bundle this and check in your Gemfile.lock for deployment.

Once you’ve done that, you should init and commit to setup your git repository.

Since we want Heroku to serve the static files, you’ll have to add the _site directory to your git repository. I found checking-in that many files to be a little unseemly, so I created a separate branch for deployments to keep the master branch clean (manually merging before deploy).

Now just add, commit, and then call heroku create --stack cedar. Once that’s finished, you’ll need to generate your files again (just to be sure they are current) and push to heroku.

You now have a blog running on Heroku!


Since converting my blog to Jekyll, it has been a wonderfully flexible solution to many of the issues that surround creating and managing a blog. There is a tremendous amount of information on Jekyll and many of the people who use it are incredibly helpful and willing to assist. When choosing a new platform, those two facts alone would merit giving Jekyll serious consideration. However, what I found was much more: a solution that was simple, elegant, and powerful.

Creating content has never been easier.


And that is the crux of the matter…

If you want to create a blerg in Rails or Sinatra, then by all means go for it. I think (scratch that, I know) you’ll find it a rewarding learning experience. I found the things that make Rails and Sinatra amazing frameworks are not just their ability to serve static files, but rather, their ability to create dynamic applications. For a blog:

Don’t waste your time building wide [features], instead build deep [content].

A blog should be simple and flexible. Jekyll helps.


Thanks for reading. Jekyll has an amazing wiki with tons of information; be sure to check there for additional details not contained in this article.

  • Sam Umbach

    Thanks for the excellent intro to Jekyll!

    Couple of questions about the rackup file:
    * Should this be stored in the project root or under _site?
    * Is the filename “rackup” or “”?

    • The file should be called `` and placed in the root dir. Sorry took so long to get to this comment. Thanks for reading. ^_^

  • No mention of Octopress…? (

    • Yes Manuel, I did not mention Octopress. Probably an oversight. It is a great tool sitting on top of Jekyll for sure. :)

  • Alex

    No mention of Github Pages? Deployment is just a matter of renaming the branch to “gh-pages”, adding github as a remote, and pushing.

    GH has a hook which runs jekyll server-side when you push, so there’s no need for Rack, and no need to check-in “_site”.

Get the latest in Ruby, once a week, for free.