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 jez.io 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 zimmerman.io domain name: my blog and my personal site. I host my personal site at www.zimmerman.io, but you can also navigate to zimmerman.io and end up in the same places as before. It’s served as a User Page from this repo.

I host my blog at blog.zimmerman.io, 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 z1mm32m4n.github.io. This was counterintuitive to me, because I thought at first that this would make my blog.zimmerman.io 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 ‘blog.zimmerman.io’. 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 www.zimmerman.io. 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 z1mm32m4n.github.io 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 zimmerman.io, send it to me!” GitHub merely notices that there is a repo with a CNAME containing ‘www.zimmerman.io’, 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 (www.zimmerman.io to redirect to zimmerman.io), I would have still created a CNAME file, but it would have contained zimmerman.io 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.)

Recap

My CNAME Files

  • For www.zimmerman.io:
    • CNAME file contains www.zimmerman.io
    • CNAME file resides in master branch of User Pages repo for jez
  • For blog.zimmerman.io
    • CNAME file contains blog.zimmerman.io
    • 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 comment, open an issue, or send me an email.

Reach for Markdown, not LaTeX

Writing should be a pleasant experience. With the right tools, it can be. LaTeX is powerful but cumbersome to use. With Markdown, we can focus on our writing, and worry about the presentation later. Pandoc can take care of the presentation for us, so the only thing left to do is start. Continue reading

Vim and Haskell in 2016 on OS X

Published on August 03, 2016

Let’s Have a Chat about Encryption

Published on April 17, 2016