I’ve been using github for some time to host code.  What I never knew was that I could create html pages (a “site”) for each project, as well as my account as a whole.  I got on the trail of this feature when I noticed my favorite game, 2048, was hosted on a “github” domain.

There is a reserved branch name (“gh-pages”)  which is the root of your project’s site.  Anything in that branch will be served-up from the “<your_user>.github.io/<project>” sub-domain.  For example, today I registered “billsco” as a user (ditching my old, crufty github junkyard).  I now have billsco.github.io as the page for my account (in the specially named “billsco.github.io” repository I created).  For the “Dot Game”, I now have billsco.github.io/dotGame.  All are addressable from the browser, and don’t show the contents as a repository but rather as a web site.  Neat.

What I could not work out was how to keep my apps on “master” yet serve them up from github.io.  I’ve decided to just do development out of “gh-pages” so my changes are instantly visible after a push.   I used my landing “billsco.github.io” page as a holder for links to those apps.

As a reminder for myself and pointer to others, here is the recipe such that a “master” isn’t created for a repo (minimizing the chances of screwing-up and not committing to “gh-pages”).

• Create a new repo (“foo”) using the github UI.  Don’t add the “README.md” or any other files.
• On your local machine, create a repo with the same name, and create the “gh-pages” branch:

$ mkdir foo;cd foo
$ git init
$ git commit --allow-empty -m "Something to branch from"
$ git checkout -b gh-pages
$ git remote add origin https://github.com/<your_user>/foo.git
$ git push -u origin gh-pages

• From now on when you clone, you should automagically be in the “gh-pages” branch.