Blogging With Jekyll Quickstart

If you want to blog these days, you have a number of choices. You can use a free hosted service like Google's Blogger or the ever-hip Tumblr, or you can host your own blog using something like Wordpress. Or, if you want a simple setup with no databases or WYSIWIG editors, you can go the static site generator route using Jekyll.

We'll run through the basics of Jekyll so you can try it out too. This post will quickly cover just enough about installation, setup, YAML Front Matter, writing blog posts, and deploying on GitHub for you to get started. For definitive information see the README and wiki on the project's GitHub page.

Feel free to download the code for this example on GitHub.

The Setup

This article was written using Ubuntu 11.10 running under VMware Player on Windows 7. The version of Ruby is:

robert@ubuntu:~/projects$ ruby -v
ruby 1.9.3p0 (2011-10-30 revision 33570) [i686-linux]

What's the Deal With Jekyll?

Jekyll is a Ruby static site generator; it's code that takes input data like what layout you want to use, what page title to use, and the actual page content you're trying to publish, and it generates an HTML page. In particular, Jekyll is useful for writing blog posts. Once you establish the structure of your posts (i.e. the layout), you can concentrate on just writing the actual content of your post. What you're left with is just static content that you can post on any webserver without having to worry about things like setting up a database to store your posts, because your posts are just files.

This approach isn't for everyone of course, but it's definitely worth giving a try. Jekyll was created by Tom Preston-Werner of GitHub fame, and it is also used by GitHub for GitHub Pages. GitHub Pages can be used for both a blog and project pages on GitHub, and we'll be using it to publish a blog to the web using git and GitHub. This setup allows you to quickly and easily setup and publish a blog or website.

Installation and Setup

Installing Jekyll is pretty simple:

robert@ubuntu:~/projects$ gem install jekyll

There are other features you can install, but we'll stick with the default setup (see the Install page on the Jekyll wiki for more details on adding features like syntax highlighting in your posts). Now we can use the jekyll command at the command line.

Jekyll Setup

When you start a project with Jekyll, you need to create a particular layout that Jekyll understands. We'll just reference the Jekyll Usage instructions directly to show you the layout you'll need to start with:

.
|-- _config.yml
|-- _includes
|-- _layouts
|   |-- default.html
|   `-- post.html
|-- _posts
|   |-- 2007-10-29-why-every-programmer-should-play-nethack.textile
|   `-- 2009-04-26-barcamp-boston-4-roundup.textile
|-- _site
`-- index.html

From the top down:

  • _config.yml: YAML formatted configuration file that can hold information like how many posts to display per page or what base URL to serve your site from. You can start with an empty file, and Jekyll will just use default settings.
  • _includes/: Put any partials (reusable bits of code) here so you can use them in your layouts and posts. You can start with nothing in this directory, and as you create more and more posts or if you decide to have multiple layouts, you'll find that you can extract common code into partials.
  • _layouts/: Put your templates here. These are useful for wrapping common elements around your posts and any other content you want to publish. You can specify what layout to use for individual posts/files. In your layouts, you use the tag {{ content }} to indicate where post or file contents will be inserted.
  • _posts/: Put your blog posts into this directory. Again, these are just HTML, Markdown or Textile files, and they are just the content part of the post. The file names should be of the format year-month-day-title.markupextension. So if you created a blog post in HTML called "Hello World" published on January 1, 2012, you would name the file 2012-01-01-hello-world.html.
  • _site/: Jekyll puts its output in this directory. The content in this directory is your site in HTML format.
  • index.html: The root page of your blog.

So to get started right away, you only really need to create two layouts, your first blog post, and the root page for your blog. Any other directories will be copied over by Jekyll, so you could have an assets directory with images and css subdirectories to hold your images and stylesheets.

YAML Front Matter

Jekyll will process files only if they have YAML front matter, which just looks like this:

---
layout: post
title: Hello World
---

In the YAML front matter, you specify variable name/value pairs in between three dash characters, and these variables become available in your layout and posts using liquid tags. For example, to access the title you would use this tag - {{ page.title }}.

The layout and title variables are all you really need to get started. You'll use the title in your layout to specify the blog post HTML page title, and you use the layout variable to tell Jekyll which layout (from your _layouts directory) to use for the file being processed.

Writing Your First Blog Post

Now you should know enough to get started using Jekyll. We'll start by creating the directory structure discussed earlier for our blog, and we'll create everything in a directory called jekyll-quickstart:

robert@ubuntu:~/projects$ mkdir jekyll-quickstart 
robert@ubuntu:~/projects$ cd jekyll-quickstart
robert@ubuntu:~/projects/jekyll-quickstart$ mkdir {_layouts,_posts,_site}

Then we'll create an empty configuration file.

robert@ubuntu:~/projects/jekyll-quickstart$ touch _config.yml

Since it's empty, Jekyll will just use default settings, but it's good to have it when we're starting out since we'll be checking it in with git. As you continue working with Jekyll, if you have the need to set configuration options in your _config.yml file. See the Configuration page on the Jekyll project page for more information.

Now that we have the minimal layout done, we can create our two layouts; one for the blog post index, and one for our blog posts. Since we're mainly interested in Jekyll, we'll keep things simple. Our index layout looks like this:

---
layout: default 
title: Hello World Blog
---

<!DOCTYPE html>
<html lang="en">
<head>
<title>Hello World Blog</title>
<link rel="stylesheet" media="screen" href="/assets/css/master.css"/>
</head>
<body>
<div id="container">
  <header class="group">
    <div class="header-inner">
      <h1 class="logo"><a href="/">Hello World Blog.</a></h1>
    </div>
  </header>
  <div id="content">
    
  </div>
</div>
</body>
</html>

Save this file in your _layouts directory as default.html. This layout template will be used for our blog home page, which will just be an index of all our blog posts. You can see that the layout is essentially just everything about the HTML page except the actual content, which we'll fill in with our index page.

The other layout we want to create, is the layout for our blog posts. Because our example is pretty simple, the same basic layout we created for our index page will work fine for our posts. Copy the default.html layout you created to a file called post.html:

robert@ubuntu:~/projects/jekyll-quickstart$ cp _layouts/default.html _layouts/post.html

So if you want to have a slightly different layout for your posts (e.g. you want your blog posts to have a sidebar), you would change your post.html layout. And if you had a particular post that you wanted to layout differently than any other post, you can create another layout just for that post, and then you would connect the post to the layout in the YAML front matter. Just to add a tiny bit of variety to our layouts, we'll add a bit of HTML to our post.html layout, which adds a link back to the blog index page at the end of each post. Open _layouts/post.html and change the <div> with id="content" to look like this:

.
.
.
<div id="content">
  <section id="main" class="group">
  {{ content}} 
  <div>
    <a href="/">Back Home</a>
  </div>
  </section>
</div>
.
.
.

Creating the Index Page

Now that we have our layouts, we'll start by creating our blog home page, which will just be a list of all our posts. Jekyll uses Liquid for template processing, and you can read more about the different tags you can use with Jekyll at the Liquid Extensions page of the Jekyll project. For our index page, we'll just need a few tags and one filter.

We'll start by using the for tag to loop through all our posts:

<ul>
{% for post in site.posts %}
<li>...</li>
{% endfor %}
</ul>

You can probably guess that this code just loops through all our site's posts, and we're going to populate an unordered list with information from each of our blog posts (everything in our _posts directory). We'll fill in the loop with each post date and title:

<span class="post-date">{{ post.date | date_to_string }}</span> <a href="{{ post.url }}">{{ post.title }}</a>

Jekyll makes a lot of data available to you when processing blog posts, and you use Liquid tags to grab this information. In this case, we're using date, title, and URL of each blog post. We also use a Jekyll specific Liquid filter date_to_string that converts our post date to a string for output. See the Template Data page on the Jekyll project page for a complete list of all the data available to you.

Add Some CSS

We won't spend too much time on this point, but just to add a little bit of style to this blog so as not to look too plain, we'll add some CSS to our blog. Adding the CSS also demonstrates how we can add whatever other directories we want to our Jekyll site layout (aside from the necessary directories like the _layouts directory), and they are copied over to the _site directory where we can reference them in our posts and layouts.

If you noticed in our default.html and post.html layouts, we have a link to our master.css file, which is in the assets/css directory:

<link rel="stylesheet" media="screen" href="/assets/css/master.css"/>

You'll of course need to create these directories first:

robert@ubuntu:~/projects/jekyll-quickstart$ mkdir -p assets/css

When we run Jekyll later on, it will copy over our assets directory and the css subdirectory. You can grab the CSS at the GitHub repository for this project.

Writing Our First Post

We don't have any posts yet, so let's write one before we run Jekyll and check out our blog. Remember that you can write your posts in HTML, Markdown, and Textile; our first post is just going to say "Hello World", so we'll just stick with HTML. We'll date our post for January 1, 2012, so we'll name the file for our post _posts/2012-01-01-hello-world.html:

---
layout: post 
title: Hello World
---

<h1>Hello World!</h1>
<p>
Bacon ipsum dolor sit amet pastrami ribeye turducken short loin
biltong. Kielbasa t-bone ham hock short ribs, sausage ribeye prosciutto
salami sirloin. Pancetta rump pork loin, prosciutto short loin bacon pork
pork chop andouille jerky t-bone meatball shank. Meatloaf fatback pork short
loin andouille. Sausage pork chop prosciutto tail turkey ball tip. Jowl
shoulder jerky beef ribs hamburger bacon, short ribs leberkase flank
meatball filet mignon spare ribs brisket sausage. Swine meatball pancetta
t-bone shoulder, corned beef frankfurter pork.
</p>

We added a little Bacon Ipsum to fill out our post. Now we have everything we need to run Jekyll.

Using Jekyll

Compiling our Jekyll site is very simple. Just run jekyll from the command line in the root directory of your Jekyll site:

robert@ubuntu:~/projects/jekyll-quickstart$ jekyll
WARNING: Could not read configuration. Using defaults (and options).
Invalid configuration - /home/robert/projects/jekyll-quickstart/_config.yml

Building site: /home/robert/projects/jekyll-quickstart -> /home/robert/projects/jekyll-quickstart/_site
Successfully generated site: /home/robert/projects/jekyll-quickstart -> /home/robert/projects/jekyll-quickstart/_site

This will compile your site and generate its output in the _site directory. Don't mind the WARNING - Jekyll is just complaining that we have an empty configuration file and that processing will continue with default settings. Once you add any configuration you need for you site to your _config.yml file, this warning will go away.

You can now run Jekyll's bundled web server to check out your site:

robert@ubuntu:~/projects/jekyll-quickstart$ jekyll --server
WARNING: Could not read configuration. Using defaults (and options).
Invalid configuration - /home/robert/projects/jekyll-quickstart/_config.yml
Building site: /home/robert/projects/jekyll-quickstart -> /home/robert/projects/jekyll-quickstart/_site
Successfully generated site: /home/robert/projects/jekyll-quickstart -> /home/robert/projects/jekyll-quickstart/_site
[2012-01-06 00:00:56] INFO  WEBrick 1.3.1
[2012-01-06 00:00:56] INFO  ruby 1.9.3 (2011-10-30) [i686-linux]
[2012-01-06 00:00:56] WARN  TCPServer Error: Address already in use - bind(2)
[2012-01-06 00:00:56] INFO  WEBrick::HTTPServer#start: pid=9462 port=4000

Your site will be available at localhost:4000, and if everything went well, you should see your blog index page:

If you click on the Hello World link you should see the post that we wrote earlier:

Notice the link back to the blog home page, so we know that our _layouts/post.html layout is being used.

To verify that our index page will actually loop through all our posts, you can create a couple more posts. I created one titled "Hello Again" and another called "Bye For Now". Run jekyll again so that the new posts are processed, start the server with jekyll --server (if it's not still running; if you start the server in another terminal, you can leave it running, and any changes you make will be visible when you refresh the page), and you should see your new posts listed on the index page:

The last thing you'll want to do is publish your blog. You can use some free webhost, or maybe you already have a hosting service, and you could deploy your _site directory there. Or you can go the easy route and just use GitHub to publish your blog.

Deploying on GitHub

If you're a GitHub user and you want to get your blog up quickly, GitHub makes it pretty easy for you. If you don't have one yet, just give in and create an account like everyone else (just kidding, there are other good options for your source control needs like bitbucket). The only other requirement is that you have git installed and you're at least familiar with basic git usage. We won't cover that that here as there are quite a few good resources on using git.

The one thing you need to note from your account is your username. Then all you need to do is create a repository called username.github.com, where username is your GitHub username. Then in the root directory of your Jekyll site, init a repository:

robert@ubuntu:~/projects/jekyll-quickstart$ git init

Before we add and commit the code, we'll create a small .gitignore file so we track the generated site in the _site directory (since jekyll will be run on our repository through GitHub Pages). Since I use vim, I also add an entry for the temp files created by my editor:

*.swp
_site/

Now you can add and commit your code:

robert@ubuntu:~/projects/jekyll-quickstart$ git add .
robert@ubuntu:~/projects/jekyll-quickstart$ git commit -m "Initial commit."

Add a remote reference to your GitHub repository:

robert@ubuntu:~/projects/jekyll-quickstart$ git remote add origin git@github.com:rsese/rsese.github.com.git

Finally, push your code to GitHub:

robert@ubuntu:~/projects/jekyll-quickstart$ git push -u origin master

It takes few minutes for your site to become available, but eventually, if you visit http://username.github.com, you should see your blog index page. And the great thing is, the only thing you need to do to publish a blog post is to add, commit, and push your code, and it will be added to your blog.

References and Further Reading

Background Information

See the GitHub project page for definitive information on Jekyll.

  • mojombo/jekyll - GitHub. Retrieved December 2011.
    Official GitHub project page - should be your first stop for definitive information on Jekyll. See especially the pages on Usage, YAML front matter, configuration, Template Data, and Liquid Extensions.
  • Introduction to Pages. Retrieved December 2011.
    Introduction to GitHub pages and how to deploy your content for your user page or project page using git and GitHub.
  • Preston-Werner, Tom. Blogging Like a Hacker. Published November 17, 2008. Retrieved December 2011.
    Preton-Werner's announcement of and rationale behind Jekyll.
  • Sites. Retrieved December 2011.
    A big list of sites that are built with Jekyll; there's a lot of interesting sites to peruse, and they all have links to the source code to give you a number of ideas for developing your own blog.
  • Liquid. Retrieved December 2011.
    Home page for the Liquid templating language used by Jekyll for template processing.

Articles and Tutorials

There is a good number of articles on using Jekyll, so feel free to use your favorite search engine and search for "blogging with Jekyll" (you'll also find a lot of posts about why someone decided to give Jekyll a try, and how they customized their setup). Here's a couple of good resources to help you work with Jekyll.

  • Sornberger, Kevin. Blogging With Jekyll and Github. Published March 1, 2011. Retrieved January 2011.
    Nice concise hands-on introduction to using Jekyll and GitHub.
  • Burgess, Andrew. Building Static Sites with Jekyll. Retrieved January 2011.
    A bit more detailed walkthrough of how to build a site with Jekyll. The final product is a photo portfolio site with a bit more emphasis on the design of the site.

Related Projects

Two projects built off of Jekyll; Jekyll-Bootstrap gets you started with Jekyll quickly and gives you a good point to start from, while Octopress goes a bit further by giving you additional functionality out of the box.

  • This is Jekyll-Bootstrap. Retrieved December 2011.
    Bootstrap project to get up and running with Jekyll quickly (e.g. takes care of the manual setup for you). Also has a great introduction to Jekyll as well.
  • Octopress. Retrieved December 2011.
    Another project that helps you get up and running with Jekyll, but Octopress also starts you off with a number of plugins and liquid filters out of the box as well as a default theme.

Git

The Git Community Book and Pro Git are two fairly comprehensive references on using git.

  • Help.GitHub - Welcome. Retrieved December 2011.
    Easy to follow tutorial on Git that starts with the basics and then moves on to more advanced usage.
  • Git Community Book. Retrieved December 2011.
  • Chacon, Scott. Pro Git. Retrieved December 2011.