GitHub Pages Custom Domains

May 06, 2014

I stumbled at first getting the DNS configured for my blog, because I’ve got a slighty more complicated setup than normal. I decided to supplement the documentation GitHub Pages gives by recounting my personal example and the setup that worked.

UPDATE: Since writing this post, I’ve switched to the domain for all of my static site hosting. The circumstances of what I wanted to accomplish and the corresponding instructions are still accurate, but you can no longer visit the links referenced in the post for some context of the setup for what you’re reading. As such, all links have been updated to point to the place where the resources now reside.

If you’ve never heard of GitHub Pages for web hosting, you should definitely check it out. You basically get free hosting for any static (i.e. plain HTML or Jekyll-served) website with git-push-to-deploy. You can even configure your site to be listed at a custom domain according to these instructions, which are pretty thorough. I feel like it’d help, though, to supplement this documentation with a fairly common example setup.

My setup

I have two sites which I want to host using the domain name: my blog and my personal site. I host my personal site at, but you can also navigate to and end up in the same places as before. It’s served as a User Page from this repo.

I host my blog at, and it’s served as a Project Page in this repo.

What the instructions say

The instructions say a few things very clearly (yay, documentation!).

First, if I want to use a custom subdomain (like what I’m doing for my blog) to host a repo, I can add a CNAME record with my DNS provider that points to what is in my case This was counterintuitive to me, because I thought at first that this would make my domain redirect to my personal site, but that’s not how GitHub handles it. (They’re smarter than that.)

At the same time, I need to put a file in the root of the blog’s repo (in the gh-pages branch because it’s a Project Page), called CNAME (view source) with the contents ‘’. After a little while, the DNS tables will update and everything here should work: I can now view my blog where I want it.

What the instructions say, but not so clearly

The next bit gave me some trouble at first (probably just because I was being impatient while the DNS tables were updating). The end goal was to have the www subdomain host my site and have the @ (top-level or apex) domain redirect there. If you read carefully, the instructions say to do three things:

  1. Make the CNAME file (view source) in my (User) Pages repository contain This is the domain at which I do want my site to be visible.
  2. Create a CNAME record with my DNS provider pointing to for the www subdomain. From a technical standpoint on the DNS provider’s side of things, this is the same thing we did before with the blog subdomain.
  3. Create an A record pointing the @ domain towards GitHub using the IP address they specify.

This last step is where you have to have a little faith: nowhere is there an explicit file telling GitHub, “If you get a request from, send it to me!” GitHub merely notices that there is a repo with a CNAME containing ‘’, and so they say, “Well, we may as well send this top level domain to the www domain referenced over here… I’ve got nothing better to do.”

This was a little confusing at first, because if I wanted the opposite direction ( to redirect to, I would have still created a CNAME file, but it would have contained and I would have created an A record with my DNS provider, not an actual CNAME. (I still did have to create both the A and CNAME in the end, but in this setup, the A record is referenced in the CNAME file, if that makes any sense.)


My CNAME Files

  • For
    • CNAME file contains
    • CNAME file resides in master branch of User Pages repo for jez
  • For
    • CNAME file contains
    • CNAME file resides in gh-pages branch of Project Pages repo for jez/blog

My DNS Config

Here’s a screenshot of what my records look like with my DNS provider, in case this was still unclear.

I’m personally using Gandi for domain registration because they had the cheapest .io TLD registration, but their interface takes some getting used to. (It was certainly still worth the deal I got.)

Jake on the Web

If you cared enough to read that far, you should consider following me on GitHub or paying a visit to my homepage. If this post was about one of my open source projects, make sure to star it on GitHub! I love hearing what people think, so feel free to open an issue or send me an email.

Haskell Development with Neovim

After a year and a half of using Haskell on and off, I’ve finally settled on a set of high-quality development and editor tools, using Stack and Neovim. Continue reading

Reach for Markdown, not LaTeX

Published on February 26, 2017

Troubleshooting Haskell Stack Setup on OS X

Published on August 03, 2016