Going Static with Jekyll & Deploying via GitHub for Free

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 ( 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:


  1. The command jekyll --server in the end does not let me go further.

    It says ‘command not found’ even though I am in the jekyll-boilerplate directory. Please help me.

    • Hey Hardik, this is kind of late, but instead of jekyll --server you would put jekyll serve. Hope this helps.

    • Hey Hardik,

      Sorry for letting this comment slip under the radar and thanks to Michael for responding.

      To take things a little further you can run the --watch flag make it a little more powerful.

      jekyll serve --watch

  2. Hey Hardik,
    Did you get any errors when running sudo gem install jekyll?

    Also you might need to update your RubyGems with the following command:

    sudo gem update --system

    Hope that helps.


This post currently has 4 responses. What do you think?

You can use basic HTML when posting code, please turn all < characters into &lt; or > into &gt;
If the code is multi-line, use <pre><code></code></pre>

Leave a Reply

Your email address will not be published. Required fields are marked *