Sam Heuck

Meet Jekyll the Static Site Generator - Part 2


Part II

In part 1 I discussed why I chose Jekyll to build this site and presented a high level overview of how Jekyll works. In this post, I'll dive into the depths of Jekyll and show off some of its features.

Liquid Templates

The template engine used by Jekyll is called Liquid. Liquid makes it easy to create a layout and pull in page elements dynamically.

Jekyll will compile content into a page using a layout like this:

// _layouts/default.html

<!DOCTYPE html>
<html lang="en">
    {% include %}

      {% include %}

    <div id="main">
      {{ content }}

      {% include %}
  {% include %}

Including partials

Jekyll will automatically find includes in the _includes directory.

{% include %}

Loops and conditionals

Any page that begins with a YAML Front matter block...

// predefined default variables
layout: default
category: funny
published: true
tags: cats

// custom variables
context: cats
title: Funny Cats

can declare variables which can be accessed in Liquid. This allows the conditional placement of content. For instance, you can place a sidebar on a page based on a context variable...


  {% case page.context %}
    {% when 'about' %}
      {% include sidebars/ %}
    {% when 'contact' %}
      {% include sidebars/ %}
    {% when 'home' %}
      {% include sidebars/ %}
    {% when 'blog' %}
      {% include sidebars/ %}
    {% else %}
  {% endcase %}

It's also simple to create a recent posts block with a loop...

<h3>Recent Posts</h3>
  {% for post in site.posts limit: 6 %}
  <li><a href="{{ post.url }}">{{ post.title }}</a></li>
  {% endfor %}

Site-wide variables can be declared in _config.yml. This is a convenient place to put primary navigation…

// _config.yml
  - text: about
    url: /about/index.html
  - text: resume
    url: /resume/index.html
  - text: contact
    url: /contact/index.html
  - text: blog
    url: /blog/index.html

Which can be included in the layout

  {% for link in site.nav %}
    {% assign active = nil %}
    {% if page.url == link.url or page.layout == link.layout %}
      {% assign active = 'class="active"' %}
    {% endif %}
    <li><a {{ active }} href="/{{ link.text }}/">{{ link.text }}</a>{{ indicator }}</li>
  {% endfor %}


Out of the box, Jekyll is well equipped to create a blog with a custom layout, and it has built in support for markdown. But augment Jekyll with plugins and you can start cooking with gas.

Jekyll Asset pipeline

This is an essential plug-in for Jekyll that will compile sass, and also aggregate and compress javascript and css.

~ gem install Jekyll-asset-pipeline

You have to install a compressor. I like the yui-compressor because it will minify both javascript and css.

~ gem install yui-compressor

Once these Ruby gems are installed, enabling the asset pipeline plug-in is as simple as putting a config file inside the _plugins directory. Here's the one I use for this site…

require 'Jekyll_asset_pipeline'

module JekyllAssetPipeline
  class SassConverter < JekyllAssetPipeline::Converter
    require 'sass'

    def self.filetype

    def convert
        :load_paths => ['.','../_assets','_assets/sass','../_assets/sass'],
        :syntax => :sass

  class CssCompressor < JekyllAssetPipeline::Compressor
    require 'yui/compressor'

    def self.filetype

    def compress

  class JavaScriptCompressor < JekyllAssetPipeline::Compressor
    require 'yui/compressor'

    def self.filetype

    def compress
      return => true).compress(@content)

The asset pipeline plug-in hooks into Liquid and looks for assets to include inside the _assets folder.

Adding javascript looks like this:

{% javascript_asset_tag global %}
  - /_assets/js/jquery.js
  - /_assets/js/highlight.js
  - /_assets/js/init.js
{% endjavascript_asset_tag %}

And css:

{% css_asset_tag global %}
  - /_assets/css/normalize.css
  - /_assets/screen.sass
{% endcss_asset_tag %}

Including any file ending in .sass will cause asset pipeline to compile the sass into css on site build.

I also like to use a plug-in for sitemap generation. Just include it in the _plugins directory and a sitemap will be automatically generated on site build.


Thor is an alternative to Rake. I like to use it as a helper for creating posts and deploying my site. Thor has some nifty features.

~ gem install thor

A Thor task for creating posts:

class Site < Thor
  include Thor::Actions

  desc "post", "create a new post"
  def post
    title = ask("Title:")
    @title = title
    @description = ask("Description:")
    @category = ask("Category:")
    @date ='%Y-%m-%d %k:%M:%S')

      filename = "#{'%Y-%m-%d')}-#{title.gsub(/\s/, '-').downcase}.md"
      template "_thor/templates/post", "_posts/#{filename}"

    if ENV['EDITOR']
        system("$EDITOR _posts/#{filename}")
      system("vim _posts/#{filename}")
// Thor template for posts
// lives in _thor/templates
layout: post
published: false
date: <%= @date %>

title: <%= @title %>
description: <%= @description %>
category: <%= @category %>
image: <%= @image %>

From the command line, run thor site:post and it will prompt for info about the post - title, description, category and an image - and then create a file in _posts and open that file in your editor.

Thor could also be used to run Jekyll, and then rsync the contents of _site to a server for easy deployment.

You can also use Jenkins for deployment. For this site, I have the Jekyll stack and Thor installed on my host server. I then use Jenkins to run the thor deploy task which copies the contents of _site into the public html folder on my host. Updating my site is as simple as writing some content, saving that content into version control, and then running the Jenkins build.

Taking this one step further, you could have Jenkins watch a remote repository for changes, and automatically run a build and deploy whenever it sees a change in the code base. That way, the site would be updated every time you pushed changes to your repository.

So go start using Jekyll! Trust me, it's fun...