Set Up a Custom Domain for Your GitHub Pages

In addition to offering free hosting through GitHub Pages, GitHub allows you to use your own custom domain name for the pages you create. Instead of using a URL like {username}.github.io/{project-name}, you can have a more personalized domain such as www.myawesomeblog.com.

This is an excellent opportunity for free open-source projects that lack financial support to host their website or blog without worrying about bandwidth limits or unexpected costs if the project gains sudden popularity. Numerous projects utilize this feature, including Bootstrap, Jekyll, Yeoman, and Foundation, among many others.

In our previous article about Jekyll, we demonstrated how to deploy a Jekyll-powered blog to GitHub Pages using the standard GitHub domain format. In this guide, we will show you how to set up a custom domain for that blog.

Note: We assume you have followed our previous tutorial, installed the GitHub app, and created a GitHub Pages site for your blog.

Creating a CNAME File

First, open the GitHub app (for Mac, for Windows). From the Branches pane, switch to the gh-pages branch.

Next, create a new file named CNAME in the root directory of your local Git repository. Enter your custom domain name for the website or blog in this file, for example, blog.domain.com. Note that you can only add one domain name in the CNAME file.

Afterward, commit and push the file to GitHub.

Pointing DNS

Next, you’ll need to configure your DNS to point your custom domain to GitHub Pages. In this example, we’ll use cPanel. Log in to cPanel and navigate to the Advanced DNS Zone Editor.

Then, add a new CNAME record pointing to your GitHub Pages site.

Finally, wait for the DNS to propagate; this may take anywhere from a few minutes to 24 hours. Once it’s complete, you should be able to access your website or blog through your custom domain name.