Sam Heuck

Meet Jekyll, the Static Site Generator - Part 1


Jekyll is a static site generator written in Ruby that uses the Liquid template engine. In combination with git for version control and Jenkins for deployment, Jekyll is a powerful tool not just for blogging, but also for small to medium- sized websites. Give Jekyll a try, and you can blog like a hacker.

First, a minor diatribe...

Web sites used to be simple. A little HTML, some text and maybe an image or two. When you wanted to add content to a site, you would simply upload some html to the server with an FTP client, and your new content would be live. Someone would request to view that page, and the server would serve the HTML requested. No databases had to be queried, no code had to be interpreted by the server, and because of the simplicity, the site was fast and secure. Sometimes, when I am neck deep in a Drupal site trying to wrangle it into submission, I think to myself "Wow, whatever happened to just uploading an HTML file...".

Enter the static site generator...

So what if, instead of using an application stack powered by PHP and MySQL to create web pages on the fly, a website were compiled, in effect frozen into a static state, and then served to the client browser. Just like the good old days! Jekyll is an open source project written in Ruby by github co-founder Tom Preston-Werner. Designed for blogs, and flexible enough that it could be used to create just about anything, Jekyll is a tool that does exactly that. It gathers up content, styling and javascript, organizes it into a predefined directory structure, and writes the necessary HTML.

Advantages of static websites


Web servers were originally designed to do one thing, serve a document. With Jekyll, that is exactly what your web server is doing. It doesn't have to provision an instance of the PHP interpreter to execute expensive code. No database queries have to be made. Content is simply... delivered.


Because there is no backend application, there can be no database injection attacks, session highjacking, or malicious cross-site scripting.

Version Control

Jekyll is designed to pair with source code control systems like Git. This means your posts are automatically versioned and can easily be backed up on github or bitbucket.

Easy deployment

How do you deploy a static site? Copy the files to the server. Done. With source control, this is a trivial push and subsequent pull. You could also use rsync, or even plain old FTP to send files to the server. The 1337 among us might like to use Jenkins and a post commit hook to automatically build and publish the site, but that requires some extra setup server side. No matter how you deploy, though, static sites make it painless.

Free Hosting!

For simple sites, you can use github pages or Dropbox to store and host your website. This isn't right for everyone, but free hosting is a nice perk. Github pages is a great option for coders. You just have to create a repository using your account name and anything in the master branch will be published using jekyll.

Disadvantages of static site generators


There is no database. Anything that requires persistence, such as comments, will need to be outsourced to a service. Also database access of any kind has to be managed from the front end. This isn't a huge problem with javascript frameworks like Ember and Backbone, but if you are used to server-side coding, there is a learning curve.

This is not Wordpress...

There is a reason this is called blogging like a hacker. You need a solid HTML & CSS background, and some knowledge of how to install, maintain, and configure Ruby gems. You need to know how template engines work. And you also have to be willing to spend some time sifting through issue cues and bug reports when you run into an problem. If "user friendly" and one button install is what you're looking for, Jekyll is not for you.

The basics

When jekyll runs, it will copy all files and folders in the project root into its build directory except for directories and files with a preceding underscore. You can also specify files to ignore in _config.yml. A typical site might look something like this:


When the ~$ jekyll command is issued, the site is generated inside the _site directory. _layouts contains the main template files, and _includes can be used for content partials which can be placed into pages with Liquid. Any file that begins with:

layout: default
title: a page
foo: bar

... will be parsed by Jekyll. This special header is the YAML Front Matter block. There are some reserved variables like layout, and publish, but you can also add any variable you need. For example, you could have a variable called sidebar that could be used to include a specific piece of sidebar content on a specific page.

Jekyll relies on the Liquid template engine to compile content. The syntax is intuitive and I found the learning curve for Liquid to be smooth and easy. Jekyll will parse Liquid include statements and search for the included content inside the _includes directory automatically. You don't have to worry about registering paths to things.

One of my favorite features of Jekyll is that it has built-in support for Markdown. You can write posts in plain text, and Jekyll will convert the Markdown into HTML. For example, paragraphs of text will be properly wrapped in <p> tags, and any text surrounded by asterisks will be bold. Jekyll has support for several Markdown engines; I like to use Kramdown (

This constitutes the basic stack for Jekyll. Write content in Markdown, create layouts for different types of content, and separate out partial blocks with Liquid includes. Then run ~$ jekyll from the project root, and upload the contents of _site to your webserver.

I built this site in Drupal, and then discovered Jekyll. I promptly redesigned my site using Jekyll and I haven't looked back. In that process I discovered some essential add-ons and helpers for Jekyll. The next post will be a tutorial on some of what I learned.

  • Jekyll plugins
  • Automatic sass compilation with Jekyll
  • Automatic compression of CSS and javascript using yui-compressor
  • Workflow helper tasks with Thor, a Rake alternative
  • Sitemap generation on build
  • Deployment with Jenkins

So stay tuned, and happy coding!