The automatic generation of project pages (http://pages.github.com) offered by Github is great, sicne you can use your README.md file as content for this site. The issue is that after the first initialization, if you change the README.md of your project, the gh-pages sites does not pick up the changes automatically. It was not obvious for me at first, but here is how you can (somewhat) keep your sanity when trying to keep your README.md file and your gh-pages sites in sync:
Convert your README.md to HTML (the Markdown Textmate bundle provides a shortcut for this, but you can use any command line tool as well).
Copy/paste that HTML between the
<section></section> of the main content div.
Check with jekyll that the rendering is ok:
Commit and push.
I was very surprised to see that you have to do it manually by yourself (contrary to http://documentup.com for instance), but it’s not that difficult after all.