Find file
Fetching contributors…
Cannot retrieve contributors at this time
148 lines (123 sloc) 5.14 KB
layout title author categories
Getting Started with Jekyll
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:

Full source code for example can be found at:


  • 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.


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

{% highlight bash %} gem install rdiscount gem install jekyll {% endhighlight %} 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: {% highlight bash %} _config.yml _includes/ _layouts/ _posts/ _site/ index.html {% endhighlight %}

  • _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

{% highlight yaml %} auto: false pygments: true markdown: rdiscount permalink: pretty rdiscount extensions: [smart] {% endhighlight %}

  • 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 we use a custom one: /:year/:month/:day/:title/

Writing an includes

_includes/widget1.html {% highlight html %}


  • Red
  • Blue
  • Green

{% endhighlight %} 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 {% highlight html %} <title>{% raw %}{{ page.title }}{% endraw %}</title>

{% raw %}{% include widget1.html %} {% include widget2.html %}{% endraw %}
{% raw %}{{ content }}{% endraw %}
{% endhighlight %} See the double curly braces? That is Liquid. Liquid is a templating language for Ruby.

Writing a post

_posts/2012-01-07-post1.markdown {% highlight yaml %} --- 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...

{% endhighlight %} 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 {% highlight html %} --- layout: default title: Posts ---

{% raw %}{% for post in site.posts %}{% endraw %}

{% raw %}{{ post.title }}{% endraw %}

{% raw %}{{ post.content }}{% endraw %}

{% raw %}{% endfor %}{% endraw %}
{% endhighlight %} 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

{% highlight bash %} jekyll {% endhighlight %} 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. {% highlight bash %} jekyll --server --auto {% endhighlight %} 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.