Matt's Blog

How to create a blog with Jekyll (like this one)

by Matt Hodan on October 27, 2012

What is Jekyll?

As described on Jekyll’s Github page:

Jekyll is a simple, blog aware, static site generator. It takes a template directory (representing the raw form of a website), runs it through Textile or Markdown and Liquid converters, and spits out a complete, static website suitable for serving by almost any web server.

Setting up a new project

Make sure you have the following installed before continuing (this is what I’m using as I write this):

We are going to use Bundler to manage our blog’s dependencies. Let’s start by making a new directory and initilize a new bundle within that directory. We will call this directory the “root directory” of your site.

mkdir [name_of_blog]
cd [name_of_blog]
bundle init

The bundle init command will create a ‘Gemfile’ in the root driectory of your site. Open it with your favorite text editor and replace its contents with the following:

source ''
gem 'jekyll'

Now install Jekyll via Bundler with this command:

bundle install --path _vendor/bundle

We include a --path variable with the command to instruct Bundler to install all gems within our project directory. You do not need to enter the --path variable when you run bundle install in the future. Bundler will automatically remember where we installed our site’s gems.

Now let’s create a home page for our site. Add a file named ‘index.html’ to the root directoy with some text with the following command (or just use your text editor):

echo "Hello World!!!" >> index.html

You now have a Jekyll-powered (albeit basic) site! Run the following commands to compile your site into static files:

bundle exec jekyll

Jekyll compiles your site by creating static files in a ‘_site’ directory located within your site’s root directory. These are the only files that should be published to your public web host. If you want to host your site on Amazon S3, I highly recommend the Jekyll-S3 gem.

Now lets launch a local web server to preview what we’ve built.

bundle exec jekyll --server

Don’t worry if you get an error that says a configuration file is missing. We will add that shortly.

Now you can view your site by visiting http://localhost:4000.

I know what you are thinking… This is neat, but I could have made this single-page site in about 15 seconds without Jekyll. True, but we’re just getting started. Next we will start to unleash some of the power of Jekyll by configuring our site to handle layouts and blog posts.

Configure Jekyll to handle layouts and posts

In the root of your project, add the following files/directories (directories are followed by a ‘/’):

Now add the following basic configuration settings to your ‘_config.yml’ file:

safe:        false
auto:        true
server:      false
server_port: 4000
baseurl:     /
url:         http://localhost:4000
source:      .
destination: ./_site
plugins:     ./_plugins
future:      true
markdown:    maruku
permalink:   date

The ‘_config.yml’ file can contain a number of configuration settings. Check out the configuration section of the Jekyll wiki for more information.

Now lets create a layout. Layouts are templates into which posts are inserted. First, create a file named ‘default.html’ in the ‘_layouts’ directory with the following html:

<!DOCTYPE html>
  <title>{{ page.title }}</title>
  <h1><a href="/index.html">My First Jekyll-Powered Blog</a></h1>
  {{ content }}

The {{ }} tag are Liquid tags that get dynamicly populated when you compile your site. Jekyll also provides several Liquid Extensions.

Now lets create our first post. Create a file named ‘1900-01-01-wayback-post.markdown’ in the ‘_posts’ directory of your project and add the following to the file:

layout: default
title: This is a wayback post

# This is a wayback post

If it were really 1900, I don't think we would be building a Jekyll site!

It is important that you use the ‘YEAR-MONTH-DAY-title.MARKUP’ naming convention, as this is what Jekyll expects. By now you should have guessed that you can use any date you like for a post.

Now run the jekyll server and go to the url of the post you just created:

bundle exec jekyll --server

You should see the page, which has been compiled into html.

We now have the beginnings of a Jekyll-powered blog. Next we will add a list of links to posts to help people navigate our site.

Add a list of posts to the layout for navigation

Open the ‘layout.html’ file that we created in your text editor and add the following code right before the </body> tag:

<h2>Recent Posts</h2>
  {% for post in site.posts do %}
    {{ }} <a href="{{ post.url }}">{{ post.title }}</a>
  {% endfor %}

Now run the jekyll server and go any page on your site and you should see a list of posts at the bottom with links to each post:

bundle exec jekyll --server

We now have a Jekyll-powered blog! I’ll leave it to you style your blog with css. You can put your css files anywhere in the root directory of your site.

comments powered by Disqus

Recent Articles