I never created a GitHub Project github.io site so I figured it was time I sat down and walked through the process. Here are a few tips for anyone who has not yet created their first github.io/project website. The focus will be on managing the site in its gh-pages Git branch which we’ll learn about soon.
I thought I’d start with an older GitHub project of mine, an application called Jangles which served me well through my transition from .NET to Java. So if I screwed up my repo it wouldn’t be a big deal. Here’s the link to the jangle-java-core GitHub repository, and here’s the github.io/jangles-java-core home page.
Creating the Site on GitHub
GitHub makes it simple to throw up a good looking project site with the url of http://[username].github.io/[project]. Go into your project settings, select “Launch Automatic Page Generator”, select a theme, copy the contents of your README.md to the site home page, and you’re good to go.
Customizing the Site: The gh-pages Branch
There are tools like Jekyll that help manage github.io sites, but if you don’t want to learn a new framework and simply work in HTML you can do so. But you first need to understand the gh-pages git branch.
The gh-pages branch is where your github.io site lives. It won’t appear on your repo unless you switch to the branch itself. If you’re using Eclipse or Sublime Text your Project Explorer will change normally when in the branch and you’ll have unrestricted editing, updating, and git processing. Here’s the Eclipse Project Explorer in the gh-pages branch.
If you’re an IntelliJ IDEA Developer like me, you’ll have some problems. Here is the identical branch shown in IntelliJ. The files in yellow “do not belong to the project” according to IntelliJ, and you won’t see any other content you’ll need to work with like stylesheets. I don’t know if its a bug or feature, through chances are good I’m simply missing something.
Setting the Upstream Git Repo
Regardless the IDE you use to manage your gh-pages branch’s github.io content, you’ll need to set the Upstream Git Repository like this:
$ git branch --set-upstream-to=origin/gh-pages gh-pages
Now you can do a $ git push in your gh-pages branch and your github.io/project site is updated.
Viewing gh-pages on GitHub
Your gh-pages content won’t display in the master view of your repository, but you can simply change to the branch in your repository as you would to view any other branch.