I was suffering from analysis paralysis trying to choose a platform for this blog. Out of the hundreds of options, GitHub Pages and Jekyll provided the right balance power and simplicity. I’ll explain why, and how to get started.

What Is GitHub Pages?

GitHub Pages is a static web host integrated with GitHub so that you can deploy a website simply by pushing to your git repository. You can see the source code of this site at its GitHub repo. This post is written in markdown and its HTML was generated by Jekyll. GitHub has Jekyll built in, so as soon as I push a new post, the site is immediately regenerated.

Setting Up The Repository

First you need to create a new github repository with the name username.github.io. Replace username with your GitHub username. Don’t add a README, .gitignore, or license yet.

Now clone the repository on your machine with

git clone git@github.com:username/username.github.io.git

Now we’re going to set up Jekyll. You will need to have ruby installed.

gem install jekyll

cd username.github.io
jekyll new .
jekyll serve --watch

Jekyll is now running your site! Go to localhost:4000 in your browser to see the basic template that was created. If you make changes to any of the content files you will see the changes reflected in the generated site. Take a look at the Jekyll Documentation for more information on configuring and building your site.

After you have your site configured and you added your content, push it to GitHub.

git push

After your first push, it will take a while for your site to show up. For me it took about 15 minutes. Once it is created, you can see it at username.github.io.

Setting Up Your Domain Name

GitHub fully supports pointing your own domain name at a GitHub pages site. They go into detail in the help doc on the subject. I’ll explain how justinhoward.org is set up.

There are two components to setting up justinhoward.org to point to justinhoward.github.io. First, I need to set up my DNS records, then I need to set up a file called CNAME in the repository.

My DNS records look like this:

@    A        192.30.252.153
@    A        192.30.252.154
www  CNAME    justinhoward.github.io.

The @ records represent the apex domain justinhoward.org. Apex domains cannot be aliased with CNAME. We need to use A records for those. Make sure you are using the latest IPs from the GitHub documentation. If you are only using subdomains, you can ignore those records. The subdomain www is pointed directly at justinhoward.github.io with a CNAME (alias) record.

Now justinhoward.org and www.justinhoward.org will both go to the GitHub Pages site. However, GitHub doesn’t know which domain to prefer. Try typing justinhoward.org into your browser. You’ll see it gets redirected to www.justinhoward.org. To do that, you need to have a CNAME file in the root of your repository.

The file should contain the domain you want as your primary domain.

www.justinhoward.org

Next Steps

You can now set up a blog with GitHub Pages. What next? How about adding some comments? You’ll see that the comments on this site are powered by Disqus.

You’ll also want to customize your template. At the time of this writing, I’m still running the default Jekyll template. I’m planning to personalize it soon. Keep an eye out for that.