Github Pages is something as simple as a GitHub service for serving up static HTML from a GitHub repository. It’s the perfect place for project documentation, like Javadoc, and that’s what I’ve been using it for. It can also be used for blogging with Jekyll or even a complete site for your project.
GitHub Pages (hence called Pages) can be tied to a project by creating a special branch called
gh-pages, or directly to your account by creating a repository called
Also, saying it only feeds static HTML is like telling only part of the story. Pages can be used together with a couple of different templating systems (like Markdown) or as I mentioned earlier, the static blog-generator Jekyll, to easily keep a web presence for yourself or your project. As every part of a Pages page is in a GitHub repository it’s really easy to update and work with.
Pages is really quite easy to use. Wanna create a site for yourself? Follow this 5 step guide to get started.
Important: there’s currently an issue regarding Pages and pushing over http, which means, it just won’t work. So use normal Git over SSH instead.
xlson.github.comin my case)
Creating the project page is about as easy as creating a personal page, but a little different. Instead of residing in a new repository it will live in a special branch (of your project repository) called
http://yournick.github.com/projectname/when it’s ready
git clone firstname.lastname@example.org:xlson/groovycsv.git groovycsv-pages)
projectname-pagesdirectory and checkout the
git checkout origin/gh-pages -b gh-pages)
gh-pagesbranch and push to
You could work with the
gh-pages branch in your ordinary repository but I find it’s easier to manage when you have a separate folder for the page branch.
We’re just about finished, but I’m going to cover one more thing, and that’s how to use the Markdown templating system.
Create a file named
demo.markdown in your repo and add the following content:
--- title: This will be used as the title-tag of the page head --- # This is a H1 [the clickable text](http://xlson.com/) * Bullet lists are also easy to create * One more
Important: the top part containing the
title segment is required and if you skip it, no conversion from Markdown to HTML will happen.
Try pushing the new file to your
gh-pages branch, or personal repository. GitHub will turn this template into an ordinary HTML file named
demo.html using the conversions specified in the sample. Pages supports a few other templating engines (like Textile) but Markdown is the only one I use.
There’s also support for the static blog generator Jekyll (which I’ve used to create this blog). Getting started with Jekyll is out of the scope of this article, but if you’ve gotten this far, getting Jekyll running should be no problem. Check the “Getting Started” instructions over at Jekyllrb.com to get started.
I’ve had some problems with GitHub Pages and that’s where this guide comes from. I’m hoping this can help others to not make the same mistakes I did. But even with those problems I think the features GitHub provide via GitHub Pages is really great. It’s a simple way to put up both documentation and a project site, or even a blog without having to think about hosting at all.
So, in closing: Big thanks to they guys over at GitHub! :)