This document explains how to best use GitHub for versioning and display of specs.
1. [Create a new GitHub repository](https://help.github.com/articles/creating-a-new-repository). I usually name the repository with the spec's short name in lowercase. So for example, this repository is called `specs-on-github`.
2. Clone the repository locally,
3. Navigate to the repo…
git clone email@example.com:tobie/specs-on-github.git
4. …and create a new branch which you'll call `gh-pages`.
Branches named that way trigger GitHubs's [Pages mode](http://pages.github.com/). When in Pages mode, the repository's content gets automagically served from http://username.github.com/reponame. For example, the content of this repository is available at [http://tobie.github.com/specs-on-github/](http://tobie.github.com/specs-on-github/).
5. Now we want to create the spec document itself. I use ReSpec, so I simply curl the content of the default template into an
git checkout -b gh-pages
index.html page at the root of my repository:
6. We can then add it to the repository:
curl http://www.w3.org/respec/examples/template.html > index.html
7. Lets now push these changes back to our GitHub account:
git add index.html
git commit -m "Add empty doc."
8. The first time you push to a `gh-pages` it can take a little while for the code to be pushed to your subdomain, sometimes up to 10 minutes, so be patient. But it'll be ready soon enough. For instance, this document is visible at [http://tobie.github.com/specs-on-github/](http://tobie.github.com/specs-on-github/).
9. In the meantime you can visit the repository's admin page and select `gh-pages` as the default branch.
10. You can now delete the `master` branch…
git push origin gh-pages
11. …and reset `origin`'s `HEAD`:
git push origin :master
12. Finally, your `README` file should reflect the repository is used for spec work. You can just copy this repo's `README` and amend it accordingly.
git remote set-head origin -a
13. Bask in the glory of modern spec development.
curl https://raw.github.com/tobie/specs-on-github/gh-pages/README.md > README.md
# Change the links inside of the readme file
git add README.md
git commit -m "Updated README to link to live spec."
git push origin