16 Oct 2013
Github Pages - A short tutorial
Github pages is a platform for you to publish a static web page about your open source project(s) on Github.
Good examples of Github pages:
An “abused” example of Github pages:
Github pages have a url that goes like this:
http://<your username>.github.io/<project name>/
For example, my Github username is
yanhan, and the project name I’ve showed
algo_ghackers, hence the url.
Now, if you go to the repository for Infinity.js and take a look at its branches, you will see something like this:
Notice that alongside the master branch, there is a
gh-pages branch. In fact,
the contents of the
gh-pages branch of Infinity.js is exactly what is used for
its Github Pages webpage at
This applies in general for all Github projects.
If you want to create a Github Page for your Github project, here are the steps:
git checkout --orphan gh-pages
This will create an orphan branch called
gh-pages. Based on the
git-checkout manpage, the first commit on an orphan branch has no parents,
so it is disconnected from the history of your repository. This is perfect for
our use case, after all, the history of the source code of a project probably
should not feature as part of the history of its github page.
git rm rf .
Again, this step may be optional depending on what you are trying to do.
This means adding at least an
index.html file, and more commonly the whole
set of static content you want to display on your project’s Github page.
Refer to the Github pages official documentation
for more details.
Do not forget to make a commit when you are done.
git push origin gh-pages
Adjust the remote name accordingly if it is not
Tadah! We are done. Or rather, almost done. If you go to any non-existent Github page, such as http://pages.github.com/123123, one part says:
“Are you trying to publish one?” It may take up to ten minutes until your page is available.
In the meantime, just relax.
Disclaimer: Opinions expressed on this blog are solely my own and do not express the views or opinions of my employer(s), past or present.