Setting up a blog on Github

blogging comments edit

While this is certainly not new, it was new for me. So I wanted to make sure I recorded what I learned this weekend.

Some Context

I was having lunch with a co-worker a couple weeks ago and he started talking about hosting websites on Github. I’ve been thinking about starting a blog over the past few months, but just haven’t been able to decide on the right platform to host it on. I’ve played around with Weebly, Squarespace and even Ghost hosted on Azure, but I was looking for low cost and a reasonable level of control and none of them quite fit the bill.

I remembered seeing an article from Phil Haack some time ago talking about how he ported his blog to Github. To say that Phil inspired my site would be an understatement - I cloned his site and then started replacing images, links and posts to personalize it. Standing on the shoulders of giants. Thanks Phil!

Getting Started

The first thing I did was create a github project to host my site. I could have created a user page repository called, but since I was following Phil’s lead, I created a project called to host this blog.

Create Repository

If you’re really interested, you can read more about the difference between user and project pages at

To see something quickly, I let Github do some of the work for me. I clicked the Settings button and scrolled down to the Github Pages section and clicked the Automatic Page Generator

Automatic Page Generator

Then I entered the name of my site and selected a theme;

Pick a Theme

And that’s it. You’ll see a new branch setup in your repo called gh-pages and see files that look something like this:


Point your browser to


Github Pages are created with Jekyll, a Ruby library that converts Markdown script into HTML. It was created with blogs in mind, so it understands permalinks, categories, pages and posts, making blogging pretty easy.

If you want to be able to run your site locally, while your fine tuning the layout, you will need to install a few things. Follow the instructions here to install Ruby, Bundler and Jekyll. I also recommend that you install Python too, since Jekyll uses it to perform code highlighting.

Once you have everything installed, run from the root of your local repository

jekyll serve

and visit http://localhost:4000

Custom Domain

While it’s cool to be able to send people to a such memorable web address as, I wanted to be able to use my own domain. Luckily, Github makes it easy.

First, create a file called CNAME (I assume spelling and capitalization is important) and place it in the root of your repository. Add a single line to that file with the name of your domain, in my case

Once that is done, visit your domain registrar (I use and point your domain name to [username]


It may take a few minutes to propagate, so don’t freak out if it doesn’t work right away.

I also added a subdomain called feeds to redirect to my Feedburner site to allow me to track the three family members that will eventually subscribe to my blog.

Creating Posts

All blog posts are stored in the _posts folder. I created a folder for each year, but that is optional. If you want to work on posts and not make them public yet, store them in a folder called _drafts. You can see how them look by running Jekyll with the draft option

jekyll serve --drafts


And that’s it! If you want a different theme, there are dozens available at that you can use for your site.