Asymmetrical View

Getting Started With Jekyll

I took at look at Toby Di Pasquale’s website tonight and it inspired me to get around to sprucing up my own site.

Toby used Jekyll, a site generation and maintenance. Jekyll allows you to maintain your site using liquid (a text based templating tool), Yaml (for configuration) and Markdown (a simplified wiki-ish style markup language). Jekyll is a bit different from dynamic Blogging or publishing platforms like WordPress in that it intentionally generates your site as static content. Most of the other publishing platforms dynamically generate their content at the time the page is requested by the browser.

Jekyll allows you to refactor your content, still allowing you to use templates and simplified markup, while allowing your site to be completely static. This means you can deploy your site (or blog) to servers where you only have a web-server and no application software – it also means that your site will perform as well as your web-server can serve up static content, which is about as fast as you can get.

Setting the site up with Jekyll took only a few minutes…tweaking the css for the site and adding in some basic content took me a few hours.


You will need Ruby installed along with RubyGems. You will not need Ruby on Rails. Once Ruby and Gem are set up, follow the remaining instructions in the installation guide. A good place to start is by cloning one of the example sites:

kyle@asymmetrical-view ~/projects$ git clone git://

This will give you a point of reference for creating your own site. I made a directory and am using "git"h:ttp:// to version my site.

Create your _config.yml

I initially had an incomplete `_config.yml` when I first tried to run Jekyll and it raised an exception. Start with the downloaded example or use mine:

    destination: ./_site
    auto:        false
    lsi:         false
    server_port: 4000
    pygments:    true
    markdown:    maruku
    permalink:   date
      use_tex:   false
      use_divs:  false
      png_dir:   images/latex
      png_url:   /images/latex

Directory Structure

I created a sub-directory for each of the major areas in the site (posts, projects, contact, talks and about), a directory for the ‘blog’ posts (_posts) and for the layouts.


Set up a Layout

In the examples you’ll see a layout file in _layouts/default.html

The layouts are your page templates. The template has the surrounding portion of the HTML page, with an inner yield block for the actual page content:

  <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
  <html xmlns="" xml:lang="en" lang="en-us">
  <div class="content">
    <div style="margin-left: 22%;">
  { { content } }

Then make use of your layout, for example in my ./site/index.html, I have a Yaml front matter that specifies the layout and the page title.

  layout: default
  title: Seeking No Barriers To Abstraction
  <div class="index-body">
    <h1>Welcome to Asymmetrical View</h1>

      This is the home site of Kyle Burton on the Internet.

    <h1>Recent Posts</h1>
    <ul class="posts">
      { %% for post in site.posts limit:5 %% }
        <li><span>{ { | date_to_string } }</span> &raquo; <a href="{ { post.url } }">{ { post.title } }</a></li>
      { %% endfor %% }

Creating Posts

My posts are all in textile (markdown) format, using a similar technique as with the html files they have a front matter section and then some main content in the markup:

  layout: post
  title: Getting Started With Jekyll

  h1. { { page.title } }

  I took at look at <a href="">Toby Di Pasquale's website</a> tonight and it inspired me to get around to sprucing up my own site.

Building and Testing Your Site

To build out your site, just run jekyll. You can also run it in a simple server mode in which it will attempt to recognize when you change files (via their last modification time) and rebuild the effected portions of your site. One thing to keep in mind is that when you run jekyll with --auto it will not report on exceptions as robustly as it will when only invoked to perform teh build. The workflow I use involves perdiocally restarting the jekyll server and removing the site build directory:

  mortis@kburton-lin ~/personal/projects/this-blog/site[this-blog*]$ rm -rf _site/ && jekyll  --auto --server 4001

When I stop seeing my changes reflected in the site I’ll CTRL-C Jekyl and re-run that command.


Installing and learning Jekyll was easy and it provides me with a much lighter weight process for maintaining my personal web site.

Kyle Burton, 14 May 2009 – Wayne PA