Host a Static Website on Github Pages with Custom Domain
Table of Contents
The hardest part about getting this blog started was making a decision on the platform I wanted to use. Going into this, I was certain that I wanted to have a static blog, as it meant that I could use the GitHub Pages service to host it. By doing so I don’t have to worry about the security and hardware overhead with running and maintaining the website. Currently, there are many platforms out there to create static websites such as the popular Hugo and Jekyll. In fact there is whole collection available on Jamstack. In the end, I decided on going with Jekyll. However, when it came to host the website, I was trying to figure out how to point the GitHub Pages website to a custom domain and the DNS updated required but couldn’t quite find an exact answer and so aim to address that here.
To host a website on a custom domain using GitHub pages, there are a couple of pieces required:
- GitHub account
- Private Domain with Domain Registrar
- DNS Registrar
For my set up, I have decided to use Cloudflare as the DNS provider as I’m also using them for other domains I own.
Update the Domain Nameserver
By default, your domain registrar will use their own nameservers to find and resolve links to your websites. However, since we will be using Cloudflare we will want to remove the defaults. In SquareSpace, this is found in the domain > DNS, Domain Nameservers.
Moving to the Cloudflare dashboard, click ‘Add a domain’, write the domain name and click continue
On the next page, scroll down and select the free plan. Now, at the bottom of the page, you should see the nameservers that you need to update for your domain.
Whilst we are here, let’s update the DNS records to point to our GitHub account where the website will be hosted. Add the following three CNAME records, replacing uname with your GitHub username and the www record with your domain, ensuring that Proxying is OFF for all three records:
Head back over to your domain registrar, and add these new Cloudflare nameservers to the domain. This update can take up to 48 hours, however from my experience in most cases it will take an hour or so.
NOTE: There may also be default DNS records associated with your domain on your domain registrar, but since we are changing the nameserver we do not need to change this.
GitHub Configuration
To publish your Jekyll website (or any other static website), you need GitHub Actions enabled for the repository and a workflow that will publish the page to GitHub Pages. The action required for Jekyll can be found by navigating to the repository then going to Actions > New Workflow and searching for Jekyll. You can commit this workflow as is and it will work out of the box. By manually running the action, your website should be available at githubusername.github.io/repository, however we want to change that to be our private domain. To update this, go to the repository settings and the pages configuration. Update the custom domain field with your domain and check Enforce HTTPS to make sure we don’t get any connections over HTTP.
If all is configured correctly, re-running your GitHub actions workflow for good measure, you should now be able to access your static website at your domain. If you still can’t see your website due to a domain resolution error, or you see the domain registrar’s default landing page, you may need to wait for the different registrars to update.
Comments
A SF
Everything was easy to follow, even for a beginner. The screenshots and explanations were spot on, and the final result is a lightning-fast and secure. I highly recommend this guide to anyone looking for a stress-free setup!