I love GitHub Pages. So much so that I’ve created several websites using it. What I don’t love is setting up domain records. It’s up there with setting up email accounts and doing the dishes.
The problem
The issue I have with domain records and GitHub Pages is the documentation, it’s not very clear to the average front-end developer like myself (it might just be me though). Also setting up domain records isn’t a regular thing for me, it’s normally done at the start or end of a project that’s taken a few weeks to put together. Which means it doesn’t stay fresh in my mind. So to solve this issue once and for all I’ve created a list of all the ways you can use GitHub Pages and a custom domain.
The options
Using a name.github.io
repo with a custom subdomain, e.g. subdomain.website.com
:
Create the record
subdomain 10800 IN CNAME name.github.io.
- It will use the
master
branch - Create a
CNAME
file containingsubdomain.website.com
Using a name.github.io
repo with a custom naked domain, e.g. website.com
:
Create the records
@ 10800 IN A 192.30.252.153
@ 10800 IN A 192.30.252.154
- It will use the
master
branch - Create a
CNAME
file containingwebsite.com
Using a regular repo with a custom subdomain, e.g. subdomain.website.com
:
Create the record
subdomain 10800 IN CNAME name.github.io.
- Create a
gh-pages
branch - Create a
CNAME
file containingsubdomain.website.com
Using a regular repo with a custom naked domain, e.g. website.com
:
Create the records
@ 10800 IN A 192.30.252.153
@ 10800 IN A 192.30.252.154
- Create a
gh-pages
branch - Create a
CNAME
file containingwebsite.com
Using a regular repo with a custom subdirectory, e.g. website.com/repo-name
:
Create the records
@ 10800 IN A 192.30.252.153
@ 10800 IN A 192.30.252.154
- Create a
gh-pages
branch
Using a regular repo with a custom subdomain and subdirectory, e.g. subdomain.website.com/repo-name
:
Create the record
subdomain 10800 IN CNAME name.github.io.
- Create a
gh-pages
branch
Additional notes
It might be worth checking out this article on understanding DNS, it does quite a nice job of explaining the difference between a CNAME
and an A
record.
The conclusion
Now that I’ve have this clearly documented I won’t have to guess records every time I come to setting up GitHub Pages 👍. Hopefully this will help you as well. If you know a better way, just submit a pull request to this article. Thanks to @createdbypete and @jdennes for help on getting these right, plus @hdv and @BenjaminReid for proof reading ⭐️.
Cheers, Dave