Going Static with Jekyll & Deploying via GitHub for Free

March 04, 2013 - Jake Bresnehan

During the last six months I have been meaning to play around with one of the many static site generators to see what all the hype is about. After a bit of research I decided to head down the Jekyll path. A fair few people tend to be using Octopress and Kirby but my main reason for choosing Jekyll was this little ‘Static Site Generators‘ gist put together by Dave Rupert. In my eyes, the fact that Jekyll has the biggest community behind it gives it the winning edge, especially for when help is needed.

Turns out, Jekyll is rad! It’s a simple, blog aware, static site generator built in Ruby. It takes a template directory, runs it through Textile or Markdown and Liquid converters, and spits out a complete, static website.

Another awesome thing about it is that it also powers GitHub Pages, which means you can easily set up a GitHub repository with a dedicated branch called ‘gh-pages’ and they will kindly host your site for free!

If you are keen to get started but are a little intimidated because of the ‘Ruby’ part, maybe it’s worth rethinking because it really is super simple and all going to plan you should have a fresh Jekyll Boilerplate blog up and running locally in about 5 minutes. Add another 5 minutes and you will have it hosted on GitHub for free.

Getting the local development environment set up

A tiny bit of Git knowledge and a few terminal commands should get you out of trouble. I use a Mac, so these instructions are for a Mac. Sorry. If you are still keen then the Jekyll Wiki has all the details for getting set up on different environments.

If you don’t have Ruby already installed you can get all the details from the Ruby site or follow a well-written tutorial on NetTuts+.

Note: Xcode!!!

I had a few issues when trying to get up and running but all I had to do was install the ‘Command Line Tools for Xcode’. To download the Command Line Tools open the “Preferences”, then click “Downloads”. You should see them listed and have an option to download it.

Note: If you are still having problems I would suggest reading the Jekyll Install Details on the official Wiki.

Now all you need to do is.

sudo gem install jekyll

You can skip this next step, but one of the biggest draw cards for me with Jekyll is using markdown to write posts. So, if this also appeals to you punch this command into your terminal to install the Discount gem. The Discount gem is an implementation of John Gruber’s Markdown.

sudo gem install rdiscount

Now you just have to clone a starter repository to set up the minimum required structure to get your Jekyll blog underway. I have created a Jekyll Boilerplate repository to help you out.

git clone git@github.com:web-design-weekly/jekyll-boilerplate.git

In order to get a server up and running with your Jekyll site all you have to do is change into the ‘jekyll-boilerplate’ directory and run the following command.

jekyll --server

This command fires up a server that will host your ‘_site’ directory on port 4000. Open your web browser of choice and point it to localhost:4000.


Setting up GitHub hosting

  • Create a new repository and create a branch named ‘gh-pages’
  • Add and commit your Jekyll site to this branch
  • Push the ‘gh-pages’ branch

In your browser visit: yourGithubUsername.github.com/reponame

To take it one step further and use a custom domain, all you have to do is place a CNAME file in the root of the repository that points to your custom URL. Then set up that domain’s A-record to point to Github’s IP address (204.232.175.78). Github has some good instructions if you need some more details.

Note: Once this is all set up, grab yourself a coffee because it can take up to 10 minutes for the planets to align.

How awesome is that!

Combining version control with hosting is a win, win situation. Using version control already means pushing files to a remote server, why not use that same system to deploy for FREE?!

I have implemented this on my personal site and so far, the simplified faster workflow with automated deployments means I get to focus on the stuff that matters.


Handy Resources:

Join over 30,000 developers & designers who get the best news and articles delivered right to their inbox each week.