Jekyll and GitHub Pages is a combination that’s hard to beat. Free and lightweight, you can use this combination to host a static website or blog. Unlike most other solutions, you simply generate your content and host it statically. This means not only a fast site, but one that is immune from many security issues that other blog software encounters. The problem, of course, is that Jekyll is a bit technical to use and to get set up. Once it’s set up, though, it’s quite easy to create content.

Overview

The majority of the instructions below are one-time setup items. When you’re simply wanting to update content or add a new blog post, you only need to follow the directions under the Adding New Content section. More detailed instructions on using Jekyll can be found in the excellent documentation on the Jekyll home page.

Prerequisites

I’ll be using a Mac for this, though the instructions are very similar for a Linux machine. To get started, you’ll need:

A domain name - Having your own domain name keeps your content indepedent of the underlying blogging platform.

GitHub Setup

Once you have set up your GitHub account, create a new repository. (If you want to keep your content private, you can pay an inexpensive monthly fee.) You can name the repository anything you like, though I suggest naming it after your domain name. This is a one-time action.

Repository Creation

GitHub repository creation

Check the box to initialize the repository with a README file, choose Jekyll from the .gitignore dropdown, and add a license if desired.

Set default branch

After your repository has been created, you will want to create a new branch and set it as the default.

On the left-hand side of the screen, click the dropdown that says Branch: master, type in gh-pages, and click Create branch: gh-pages to create the branch.

Creating the gh-pages branch

Now, set your newly created gh-pages branch as the default branch. Click Settings, Branches, and choose gh-pages from the dropdown under the Default branch heading. Click Update and click through the Are you sure? notification.

Set default branch

Installing GitHub Desktop

Download GitHub Desktop and install it on your Mac. We will use this to keep a local copy of your site on your computer and synchronize changes back to GitHub with it. After installation, open GitHub Desktop, log into your GitHub account, and add the repository you created previously.

Choose File, Clone Repository, select your repository, and click the Clone button. Choose a location to store the clone. (I normally choose the Sites folder on my Mac.) This will create a subdirectory named after your repository in the folder you chose.

Installing Jekyll

There are several ways that you can install Jekyll locally. The following approach will ensure that you’re consistent with the version of Jekyll and the plugins GitHub Pages uses.

Step 1: Homebrew (for Mac only)

If you’re on a Mac, the first thing to do is to install Homebrew. Follow the instructions on the homepage. You may additionally be prompted to install OS X Command-Line Tools first.

Step 2: Ruby and GitHub Pages gems

To install Jekyll, run the following commands from the Terminal:

brew install ruby

gem install github-pages

This installs an updated version of Ruby into /usr/local/bin, as well as Jekyll and all plugins used by GitHub for GitHub Pages. More details can be found under the Installing Jekyll heading on the Using Jekyll with GitHub Pages page.

(Note: This page also mentions how to keep Jekyll updated.)

Jekyll Theme

You may choose to follow the instructions to create an empty Jekyll site on the aforementioned instructions. However, many people opt to start with a theme, which has the basic structure of a Jekyll site. There are many places to find a Jekyll theme. Some examples include:

We will use the main Poole theme. Simply choose the Download button on the right-hand side of the page. Extract the contents and place them in your local copy of your repository. Changes you need to make vary per theme, as there is no actual standard on theme creation or configuration.

Modify the _config.yml configuration file and change a few settings. For example, let’s change the follow sections:

Additional changes may need to be made to the theme pages, which are in the _includes and _layouts folders. Additional files like about.md and index.html may need modifications too.

Previewing Content Locally

Now that the basic setup is complete, run Jekyll locally to test the site configuration and see how the site looks. Being able to preview posts locally prior to generation is useful, and something you can do when working on drafts. To run Jekyll, open up a Terminal window, navigate to the main directory for you site by typing something similar to cd Sites/www.example.com, and type jekyll serve. You’ll see something similar to the content below:

Now, go to your browser and navigate to http://localhost:4000/ and you’ll see the homepage for the site if all went well.

Local browser preview of the website

If you want to make additional changes to posts or the homepage, simply make changes and save them. The changes will apply automatically when you refresh the site in your browser. Note: If you want to make changes to your configuration file, you’ll have to stop and restart Jekyll for those changes to take effect. Simply go back to the Terminal window and type Ctrl-C to stop Jekyll and type jekyll serve again.

You may want to remove the sample pages in the _posts directory and add your own first entry. Files are named using a YYYY-MM-DD-your-title-here.md convention. Drafts can be created by using your-title-here.md without YYYY-MM-DD on the front.

Code and browser previews side by side

Configuring Your Domain Name

In order to allow GitHub Pages to serve up your site from your own domain name, you need to create a CNAME file (all caps) to GitHub Pages to use your domain name instead of their default github.io name. In the top level of your repository directory, create a file named CNAME (all caps, no file extension) with the name of your site as the contents of the file. For example: www.example.com

You also must configure a CNAME entry with your domain registrar. Have it point youruserid.github.io, where youruserid is the user ID registered with GitHub.

Deploying the Site

GitHub Desktop to Commit and Sync changes

Now that you are sure that the site is set up to your liking, you are ready to deploy the site. Since you’re done testing locally, stop Jekyll in the Terminal by typing Ctrl-C. Then, go to GitHub Desktop under the Uncommitted Changes tab, type in a summary (and optional description) and click the Commit and Sync gh-pages button. If everything went well, you should see your blog online via the CNAME domain entry you created.

Deployed Site on GitHub Pages

Adding New Content

To add new content, simply create a new post. Preview locally by running jekyll serve. When you’re ready to publish a post, use GitHub Desktop to Commit and Sync and view your new content!

Quick Fixes via GitHub

If you’re not near a computer that you have Jekyll installed on and simply need to make a quick change to a page or if you want to type a post directly into a web browser editor, you can do the basics using the GitHub website interface. This interface is limited to adding or editing text content, so you can’t easily upload images. But it works in a pinch.

Simply navgiate to the repository on GitHub, navigate to the _posts directory, then either:

Alternative Ways to Add Content

Web: Prose.io

While editing directly in GitHub works, it isn’t ideal. However, Prose.io to the rescue! Prose.io was created by Development Seed to more easily edit Jekyll sites on GitHub Pages. Fun Fact: Prose was used to create and maintain the HealthCare.gov website.

You can authorize Prose to access your GitHub account and then you can edit posts or create new files (including uploading images) via a web-based editor. It even has the ability to preview content and can work with drafts or publish a page for you. Did I mention it’s free?

Prose.io editing a blog post

iOS: Working Copy

Sometimes you need to edit content on the go. With Working Copy, you can directly view and edit content from GitHub. Content can be edited directly in the application or sent to some well-known editors on iOS, including Editorial and Byword. Once you sync back to GitHub, your changes will automatically be picked up.