GitHub Pages — A Comprehensive guide w/ images (Part 2)

Kushal Bhalaik
Jan 12 · 5 min read

This is part 2 of the article series GitHub Pages — A Comprehensive guide w/ images

Photo by Sincerely Media on Unsplash

Recently I started building my personal website as everyone is building one for themselves these days. I got a cool TLD (.xyz), and that is the only money I wanted to spend. Since then I’ve been looking for ways to host it without any costs.


In part 1 of this series, we saw how to publish GitHub User Pages and how to link it with custom-domain.In this article, we’ll see how to have more than one Github Pages per account (Yes, it is possible). Commençons!!

Before proceeding make sure you already have a repository <your_username>.github.io

Setting up Multiple Github Pages:

Let’s create a new repository:

  1. Goto Github.new and fill out the new repository details, I’ll call it demo:
Repository creation flow on GitHub

Note: It is important to keep this repository public

2. Now goto repository settings:

3. On Settings page, scroll down to Github Pages section:

GitHub Repo Settings Page

4. Make the repository Public, if you see following message:

Making Repository Public on GitHub

5. Once repository is Public GitHub Pages will become enabled for the current repository

GitHub Pages options

6. Click on None, then view current options:
we can either choose following options:

  1. Using “master” branch of demo repository for publishing GitHub pages (Like in GitHub User Pages)
  2. Using /docs page under “master” branch for publishing GitHub Pages
  3. We’ll be using gh-pages branch option which is currently not available as gh-pages branch doesn’t exist for demo repository as of yet
By default None is selected for GitHub Pages

7. Copy the demo repository link:

Copying repository link from GitHub

8. Now clone the repo to local machine:
Here, <far11ven> is my GitHub username

~$ git clone https://github.com/far11ven/demo.git

9. Create a local gh-pages branch and push it to GitHub:

~$ cd demo
~$ git branch gh-pages
~$ git push remote -u origin gh-pages

10. Go back to demo settings on GitHub and select gh-pages as source for publishing:

After this step whatever you put in gh-pages branch will be automatically published.

11. Let’s create a simple index.html file within this repository:

~$ echo “Hello gh-pages!!” > index.html

12. Add, commit and push your changes to GithHub remote:

~$ git add *
~$ git commit -m “Initial commit”
~$ git push -u origin gh-pages

13. You can see in your browser demo repository has been published

“demo” page published under GitHub User page

You will have a main GitHub User Page (One per account) <username>.github.io and all other repos will be published as sub pages

or,

if you have already linked a custom-domain to your GitHub User Page, the n you can see the published page at www.example.com/<your-repo-name>
in my case demo repo will be published at far11ven.github.io/demo


Setting up custom-domains:

i) Setting up Github Pages as a domain

To have our subpages be listed as demo page we need to do following changes in our GitHub repo and our Domain provider

  1. Create a CNAME file in your repository:
    I will be doing it via GitHub UI, just create a CNAME file (with no extension) and just enter your sub-domain name inside it, nothing else.
    in my case, I want to make demo pages appear as your-website.com
CNAME File content

Once Done, commit your changes.

Adding CNAME to repository
After Adding CNAME to repo

2. Add a new DNS record on your DNS provider:
We need to change existing CNAME records to point to created GitHub pages i.e. <username>.github.io

Adding new CNAME DNS record on Cloudflare

ii) Setting up Github Pages as a sub-domain:

To have our subpages be listed as demo page we need to do following changes in our GitHub repo and our Domain provider

  1. Create or Edit an existing CNAME file in your repository:
    I will be doing it via GitHub UI, in my case, there is already a CNAME File so I ‘ll just edit the existing file and replace everything in it with my sub-domain, nothing else.
    in my case, I want to make demo pages appear as demo.kushalbhalaik.xyz
CNAME File Content

Once Done, commit your changes.

Editing CNAME file in Repository
After Adding CNAME to repo

2. Add a new DNS record on your DNS provider for existing Domain:
We need to change existing CNAME records to point to created GitHub pages i.e. <username>.github.io

Adding new CNAME DNS record on Cloudflare

Important Points:

  • Again, at this point, nothing needs to be done from our end, we need to wait for changes to reflect on both GitHub and Cloudflare end, Which may take some time (usually its prompt) but may take some time based on your DNS provider
  • You won’t be able to access your pages via <username>.github.io, or <username>.github.io/<your-repo> in case you try and enter this in the browser, you’ll be redirected to your custom domain or custom sub-domain
  • Your can-not add multiple GitHub Pages as a sub-domain to GitHub User Page i.e demo.far11ven.github.io in my case is not a valid URL

Final Result:

We have successfully created a sub-domain to host our other Github-page, follow these steps to create even more pages within your website.

GitHub pages published under a sub-domain

Cheers!!

Original article on: https://blog.kushalbhalaik.xyz/github-pages-a-comprehensive-guide-w-images-part-2

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade