Getting Started with Jekyll
February 12, 2012 by Julie Ann Sakuda

This is a short tutorial that was presented at HICapacity on February 9, 2012.

The original slide deck can be found at: http://sakuda.us/jekyll

Full source code for example can be found at: https://github.com/hicapacity/jekyll-examples/tree/master/simple-demo

Prerequisites

  • Ruby (got RVM?)
  • RubyGems

Check out RVM when installing Ruby. RVM manages Ruby version allowing more than one version of Ruby to be installed. It is easy to switch between versions and maintain different sets of gems.

Installation

Once Ruby and RubyGems are installed install the gems for rdiscount and Jekyll:

    gem install rdiscount
    gem install jekyll

Rdiscount is used here but Maruku can used instead for interpreting markdown.

Basic Directory Structure

Jekyll sites will have a directory structure that looks like the following:

    _config.yml
    _includes/
    _layouts/
    _posts/
    _site/
    index.html
  • _config.yml - configuration file. Discussed more on the next slide.
  • _includes/ - folder with snippets of HTML that can be inserted into pages
  • _layouts/ - layouts for different pages of the site
  • _posts/ - folder of posts in markdown
  • _site/ - generated by Jekyll. The rest of the folders and config file should be created by the user.

Basic Configuration for _config.yml

    auto: false
    pygments: true
    markdown: rdiscount
    permalink: pretty
    rdiscount
      extensions: [smart]
  • auto - tells Jekyll if it should monitor changes to files and regenerate the site automatically. Only applicable if running Jekyll as a server.
  • pygments - tells Jekyll that it should colorize code blocks using Pygments
  • markdown - markdown of choice
  • permalink - style of link to use for the site. "pretty" is a built in link style. For HICapacity.org we use a custom one: /:year/:month/:day/:title/

Writing an includes

_includes/widget1.html

    <div style="border: 1px solid black">
      <h3>Colors</h3>
      <ul>
        <li>Red</li>
        <li>Blue</li>
        <li>Green</li>
      </ul>  
    </div>

An include is just a snippet of HTML. All snippets must be .html files. A perfect example of when to use an include is when writing a widget! Then they can be easily integrated into a site's sidebar and easily rearranged in any order. The snippet above is just a mock "widget" that lists some colors.

Writing a layout

_layouts/default.html

    <!DOCTYPE html>
    <html>
    <head>
      <title>{{ page.title }}</title>
    </head>
    <body>
      <div id="sidebar" style="float: left; padding-right: 10px;">
        {% include widget1.html %}
        {% include widget2.html %}
      </div>
      <div id="contents" style="float: left;">
        {{ content }}
      </div>
      <div style="clear: both;"></div>
    </body>
    </html>

See the double curly braces? That is Liquid. Liquid is a templating language for Ruby.

Writing a post

_posts/2012-01-07-post1.markdown

    ---
    layout: post
    title: Post 1
    author: Test Author 1
    categories: ['Test', 'Jekyll']
    ---
    Hello World! This is test post 1.

    Nam auctor laoreet scelerisque. In porttitor varius interdum. Phasellus tempor vehicula sagittis...

See that at the top? That is YAML Front Matter. YAML front matter is a block of YAML that appears first in the file. This tells Jekyll that these files need special processing.

Displaying posts

index.html

    ---
    layout: default
    title: Posts
    ---
    <div>
      {% for post in site.posts %}
      <div>
        <h2><a href="">{{ post.title }}</a></h2>
        {{ post.content }}
      </div>
      <hr/>
      {% endfor %}
    </div>

The code is iterating through all the posts for the site. It is showing them all on one page. The title of the post is link to the individual post. Note that it is possible to add pagination to a site so that not all posts end up on one page. The code is similar to that above but uses the paginator instead. Refer to the Jekyll wiki for more information.

Generating the site

    jekyll

NOTE: I mentioned earlier that Jekyll can be run as a server. While in this mode it can monitor the directory for changes and automatically regenerate the site as changes happen.

    jekyll --server --auto

Either option will generate the site in the _site folder. If the server option was used the site can be visited in a browser. The default port is 4000.

Recent Posts