Quentin Calvez

Personal blog

Getting started with Jekyll

Jekyll is a very lightweight blogging engine that generates static HTML files from templates and markdown/textile content. It’s a good alternative to complex systems like WordPress when all you need is a very simple and non-dynamic blog.

As I had to go through the process of learning Jekyll in order to setup this blog, I though I might as well write a short tutorial on how to get up to speed quickly with this blogging engine.

Prerequisites

  1. Environment: You’ll need to have Ruby installed in order to run Jekyll. You can get more information about that here.
  2. To install Jekyll itself and its dependencies, the easiest way around is to use Ruby GEM with the following command:
$ gem install Jekyll
  1. If you plan on using Textile, you’ll also need the RedCloth gem.
$ gem install Redcloth
  1. Finally, if you need syntax highlighting for code snippets, let’s also install Pygments.
$ easy_install Pygments

Structure

Jekyll relies on a few base files and directories in order to organize the different files of your project:

Directories

_layouts
Contains the templates that we’ll use to have a common header/footer across all our pages.
_posts
Contains the blog posts. One file per post. They can be in markdown, textile or HTML format.
_includes
Where you’ll place reusable content that will be accessible from anywhere else.
_site
This one will be automatically created as it contains the files generated by Jekyll. That’s what you want to upload to a webserver in order to have your blog publicly available. It might also be a good idea to exclude it from version control.

Files

_config.yml
Main Jekyll configuration file, in YAML format.

Other files, like scripts, stylesheets, or pages like your index can go directly in the root directory, or in any subdirectory other than those I just mentioned.

Template system & YAML Front Matter

The Liquid template system allows you to use print variables anywhere using the {{...}} format. As an example, here’s a very simple layout file that we’ll call default.html:

<!doctype html>
<html>
    <head>
        <title>{{ page.title }}</title>
    </head>
    <body>
        {{ content }}
    </body>
</html>

As you might have figured out, the page.title will be replaced by whatever string we specify later, and content by the actual content of the page using this template.

We can now create our first post. Files in the _posts directory must all have the following format: YEAR-MONTH-DAY-title.format. In this case, let’s create the file 2012-12-7-my-first-post.md:

---
layout: default
title:  My First Post
---

This is my first post!
======================

Notice the first part enclosed in --- tags. This is the YAML Front Matter, it’s used to set values specific to the current file. In this case we have set the layout to use our previously created template, and the title of the current page that will be available under page.title. The rest of the file is just regular markdown.

Running Jekyll

Now that we have a first page setup, we can already generate our website for the first. In order to do that, just run the following command in the root directory of the project:

$ jekyll

There’s a few useful options that can added to this command:

—auto
The content of the website will be regenerated every time a file is modified.
—server [port]
A webserver will be launched (on port 4000 by default) for you to browse your site locally.

Configuration

Going deeper