Kyle Pericak

"It works in my environment."

Thu 27 February 2020

Github Pages: Basics

Posted by Kyle Pericak in development   

Note: There are a lot of ways to do this, I'm only documenting the approach I chose. For instance, I'm using the master branch and docs/, but you can use another branch too.

Initial Setup

CNAME file

Pick a domain name. When I was writing this post, I was setting up the GitHub Pages site for Breqwatr Deployment Tool, so I used

Create a file in your project's master branch named docs/CNAME, and put your desired FQDN in that file. Push it to master.


I'm using CloudFlare, so I logged in there and made a new CNAME entry pointing to

Repository Setup

As the repository owner, open the repo up in GitHub and go to the Settings page. Look for the GitHub Pages option.

  • Set your source to master branch /docs folder.
  • Choose a theme
  • Confirm custom domain in the "custom domain" field

Write the config file

Pull the changes GitHub made to your registry, then edit docs/_config.yml.

Give your page a title and description.

theme: jekyll-theme-slate
title: Breqwatr Deployment Tool
description: A private cloud deployment and management toolkit

Write Content

Create a file named docs/ and write your page content here.

GitHub Pages will link this file to the / path of your chosen domain.

The content is written in Markdown, which is really intuitive and carries over nicely from any files you'll have written before.


GitHub Pages supports breaking your content up into more than one static page. Create a new content file such as, and GitHub Pages will host it with a slug of /installation.

From the index file, link to your new secondary file using Markdown. Here's an example of linking to an installation guide from a table of contents list.

Table of contents

- [Installation](/installation.html)

Javascript appears to be disabled. Comments can't load.