Github pages with custom domain

Setup custom domain on the user page and then all the project pages of Github repositories will automatically appear under the same url.

Github provides two types of pages,

  • User pages
  • Project pages

User pages

It is nothing but a Github repository with a special name username.github.io and all the contents of this repository must be in the master branch. For example, pankajparashar.github.io is a repository for user pages under my Github username, pankajparashar.

By default, the user pages are available under the url,


Project pages

Project pages are project specific files lying in the gh-pages branch of the repository. These pages can be accessed via the url username.github.io/repository_name.

For example,

Repository name -> Color Stack  
URL -> http://pankajparashar.github.io/color-stack

Custom domain

Now, coming to the meat of the article, custom domain can be set for both user and project pages. Moreover, the steps to setup the domain also remains the same for both the categories. However, this article will only deal with setting up custom domain for the user pages only.

Step 1
Create the repository username.github.io on Github. For reference, check my user repository on Github.

Step 2
Add a CNAME file containing the custom domain name that you want to map. In my case, the CNAME file contains, pankajparashar.com

Step 3
Login to your domain name registrar and create a A record that maps the domain to the Github's IP address - (Infact, this IP Address no longer works and has been deprecated by Github. The new IP Addresses are, and as mentioned in this article.)

There is no guarantee that this IP address will remain the same forever. Indeed, Github has changed its value in the past. Presumably Github will notify users appropriately before any future changes. If they do change it, you'll have to adjust the configuration at your DNS registrar accordingly.

Theoretically it can take 30 mins to 2 hours for the DNS propagation to complete, but in my experience this change took 1 full day to reflect. Once the propagation is complete, whenever you visit pankajparashar.github.io you will be redirected to my custom domain pankajparashar.com.

The interesting part is that all the project pages are also being redirected under the same Top-Level domain. This is fantastic, because for years I have been trying to bring all my projects and the personal website under the same domain. This process makes my entire workflow completely seamless.

My Color Stack project, available at the url pankajparashar.github.io/color-stack is now automatically being redirected to pankajparashar.com/color-stack.