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.
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.
CNAME DNS Entry
I'm using CloudFlare, so I logged in there and made a new CNAME entry pointing
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
Give your page a title and description.
theme: jekyll-theme-slate title: Breqwatr Deployment Tool description: A private cloud deployment and management toolkit
Create a file named
docs/index.md and write your page content here.
GitHub Pages will link this
index.md file to the
/ path of your chosen
The content is written in Markdown, which is really intuitive and carries over
nicely from any
README.md 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
installation.md, and GitHub Pages will
host it with a slug of
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)