How to add GitHub Pages to a project

Overview

GitHub Pages is a static site hosting service and is designed to host personal, organization, or project pages directly from a GitHub repository.

Background

I occasionally need to add GitHub Pages (gh-pages) to a project. These instructions are based on a GitHub help article and have been customized for my use.

Steps

Create orphan gh-pages branch in doc/html directory:

1
2
3
4
5

$ cd doc/html
$ git init
$ git remote add origin `git config --file ../../.git/config remote.origin.url`
$ git checkout --orphan gh-pages
$ git rm -rf .

Create initial commit:

1
2
3

$ touch index.html
$ git add .
$ git commit -m 'Initial commit'

Configure gh-pages branch:

1
2
3

$ git config branch.gh-pages.remote origin              # optional
$ git config branch.gh-pages.merge refs/heads/gh-pages  # optional
$ git push origin gh-pages

((( - Enjoy responsibly. - )))

References

| GitHub Help / GitHub Pages Basics
| GitHub Help / Creating Project Pages from the command line