Deploy a project page or a custom subdomain on Github pages

Have you noticed the URL of this blog?

The first part, namely blog, is called a subdomain, it's a subset - a smaller part of a larger domain. In fact, www is also a subdomain, but you can make your web address unique by replacing it with almost anything you want (without spending an additional penny !). This subdomain will allow you to point to a specific directory in your Github Pages directories in order to display specific content.

In this blog post, I'll simply demonstrate how I deployed a subdomain using AWS as my DNS (Domain name System) and Github Pages as my host. I will also demonstrate how to create a project page for your Github page.

There are two possible scenarios: you either have a basic Github page or one with a custom domain.
In the first scenario, you will be able to create a project page that will work just like a normal subdomain but will be accessible like such: username.github.io/project.
In the second scenario, you will be able to create a subdomain that will be accessible in the normal way: subdomain.website.com (or any other extension you use).

Step 1: Create a CNAME record pointing to your Github page

Note: Only follow this step if you already have a custom domain set-up and wish to have a custom subdomain like the one used by this blog, otherwise, jump to step 2.

Note (2): In this tutorial I use AWS Route 53 as my DNS of choice, but these steps can be done through any other DNS out there.

Head over to your AWS DNS console (Route 53), then click on Hosted zones:

Click on the hosted zone to which you wish to add a subdomain, then click on Create Record Set:

And fill in the right-hand side form like such:

Where Name should contain your new subdomain's name (in my case blog), Type should be CNAME - Canonical name and Value should be your personnal Github pages URL.

A CNAME record is simply used to specify that a domain name is an alias to another domain name.

Please keep in mind, that in my case, christopherkade.github.io actually uses the custom domain christopherkade.com.

Finally, create your Record Set. These changes may take up to two days to occur, but that does not stop us from continuing our work.

Step 2: Create your project's Github repository and deploy it

All we have to do now, is create our project's repository and push its contents to the Github pages branch.

So head over to Github and create the repository that will be used to serve the contents of your subdomain once it is accessed. Note that the repository's name will be the value used in your new URL (for example: call you repository blog if you wish to access it via username.github.io/blog or blog.website.com)

Note: Only create the following file if you are working towards a custom subdomain, otherwise skip it.

Once this is done, add a CNAME file to the root of your project containing your new domain, in my case blog.christopherkade.com.

Then push your work to the gh-pages branch, this will automatically build your project and deploy it to your page.

1# clone your new repository
2git clone https://github.com/username/repo-name.git
3
4cd repo-name
5
6# create an index.html file to make sure everything works
7echo "Hello World!" >> index.html
8
9# create the gh-pages branch
10git checkout -b gh-pages
11
12# add the contents of your directory
13git add .
14
15# commit it all with a given message
16git commit -m "Initial commit"
17
18# push it to the gh-pages branch
19git push origin gh-pages
20

After a few seconds, your new subdomain should be up and running ! You can now fiddle around, creating a Jekyll blog or any other static website you can think of.

You can now access your project:

username.github.io/project

Or your sub-domain:

subdomain.website.extension

Summary

We have briefly learned a couple of things:

The various usages of a subdomain (and its significance)
How to create a CNAME record in our AWS DNS (and what it actually is)
How to deploy a project page or a new subdomain for our Github page

Final thoughts

This is a repeatable process, you can deploy as many projects / subdomains as you want. This can be useful if you wish to showcase one of your projects, create a blog, or simply have a safe development repository (under a dev subdomain for example).

Thanks for reading,
@christo_kade