Hosting a website on Github Pages and publishing to a Custom Domain
When you’re creating your own website and you want simple and no-frills hosting, github pages is certainly the way to go. It only allows hosting static pages though, but don’t let that fool you. From a simple webpage for a project to an online profile and even a fully functional web app, it can handle it all.
Step 1: Setting up a repository
Every github pages website needs to be in a repository. You can create a new one at https://github.com/new or use an existing one.
The name of the repository is very important here. If youre creating something like a personal portfolio, you may want your website link to be
username.github.io In this case, name the repository exactly
username.github.io replacing username with your own.
If you’re making something else and don’t want to use the root url, you can name the repository anything else. The link will now be
Step 2: Adding website files
You can store the files for your website in 3 different locations in the repo.
- master branch: This is useful when the repo you’re using is dedicated to only that website.
- docs folder in the master branch: This is useful when the repo you’re using already has some code, maybe a project that the website is about. This way you can keep the website and project code together. As a bonus, the code in the docs folder doesn’t change the langauge distribution of your repo.
- using Jekyll: Hosting using Jekyll is useful for creating a quick mini website. You can choose a theme and the readme file of your repo will be published. We won’t be going into this here.
Step 3: Setting up github pages
Head to the settings tab in your repository and scroll down till you see the Github Pages section. Choose your preference in the dropdown.
And your website is now set up! You should see a green box in the Github Pages section with the domain for your website.
You can use this domain as is, or link it to a custom one as elaborated in the following steps.
Step 4: Adding a custom domain
The Github Pages section of the settings page should now have a place for you to input your custom domain.
Type in the domain that you own in the Custom domain field.
By adding the domain name here, anyone trying to access your website through either link (the custom one or github pages one) will see only the custom one in their browser. You can skip this step if you don’t mind seeing the github pages link in the browser.
After clicking on save, you should see that a new file called
CNAME added to your code.
Step 5: Adding DNS records to your domain
Login to the website of your domain provider. Head to DNS records for your domain. Be careful here as any wrong changes can have drastic effects.
I’m using domain.com but the procedure should be the same for most providers.
Create a new DNS record of the type A and assign the name @. Add the IP address 188.8.131.52 and set the Time to Live (TTL) as 1 Hour or more. Change the TTL only if you’re aware of what it does.
Once that is done, go ahead and create 3 more new records with the IP addresses 184.108.40.206, 220.127.116.11, 18.104.22.168 with the rest of the details the same. In total you should have now created 4 records of A type DNS records.
Now create a CNAME type DNS record with the name www and TTL and 1 Hour. In the content field, insert the address that Github Pages gave you without the https and www. In my case, it would be
If you are using the root domain (without anything after the /) then add a . after the entire link. For example,
You should have finally added 5 DNS records (4 A and 1 CNAME).
DNS records take anywhere from a couple of hours to a day to propogate so stay patient.
Finally, enforce HTTPS on your website. At the bottom of the Github Pages section in the Settings page, you should see a checkbox named Enforce HTTPS. This basically means the connection between the user and the website will be secure (aka has that lock on the left of the url). I highly recommend enforcing HTTPS as it makes your site more trustworthy to users.
If you check on your domain after some time, you should see your new website!
This method should remain the same for any website hosted anywhere. Just change the IP address in the A records and the link in the CNAME record.