How to Host a Site With a Subdomain on GitHub Pages

Photo by Domenico Loia on Unsplash

Subdomain Background

Have you ever noticed some websites,, or have extra text at the front? The first bit of all of these is called a subdomain. Subdomains are domains that are a part of other domain names. They can be helpful ways of organizing sites and are easier to remember for users.

GitHub Pages has great support for free website hosting but creates new pages as [username] by default. Subdomains are a great way to make the URL easier to understand.

GitHub Pages Subdomain Tutorial

Note: this tutorial assumes you already have a custom domain setup. Check GitHub Pages documentation to setup your custom subdomain.

First, open your domain name provider and add a CNAME record. A CNAME is an alias for another URL. In the CNAME, add your desired subdomain as the host and [username] as the target. Note the extra dot after the end of io. For this tutorial, Namecheap was my domain name registrar. Creating a CNAME record will look different depending on your domain name provider.

A Namecheap CNAME record

You will be able to see the new subdomain propagate across the world with a tool like

DNS propagation needs to happen before GitHub Pages can update to the subdomain

We now need to tell GitHub to host our site at the subdomain we just created. Open the repository you would like to host at a subdomain and head to the Pages tab in settings. Select your source branch and type your subdomain in the custom domain field.

GitHub Pages Settings

Initially, GitHub Pages will throw an error saying the domain name is “improperly configured.” This error should resolve itself after a few minutes as the DNS records update. If the error doesn’t go away, try editing the custom domain, clicking save, then reverting to your desired custom subdomain. Editing the custom domain will trigger GitHub Pages to recheck the DNS records.

Waiting on GitHub Pages to sync with DNS records

Once GitHub Pages has verified the DNS records, the website will be live at an HTTP link. Now Pages will automatically certify the site to create a secure HTTPS version. The process completes after a few minutes.

Verifying website for HTTPS
Custom subdomain live at HTTPS

That’s it! Your Pages site is hosted at your custom subdomain.

Photo by Patti Black on Unsplash

Originally published at



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store