This document explains how to best use GitHub for versioning and display of specs.
Getting started --------------- 1. [Create a new GitHub 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,
git clone
3. Navigate to the repo…
cd specs-on-github
4. …and create a new branch which you'll call `gh-pages`.
git checkout -b gh-pages
Branches named that way trigger GitHubs's [Pages mode]( When in Pages mode, the repository's content gets automagically served from For example, the content of this repository is available at []( 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 index.html page at the root of my repository:
curl > index.html
6. We can then add it to the repository:
git add index.html
        git commit -m "Add empty doc."
7. Lets now push these changes back to our GitHub account:
git push origin gh-pages
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 []( 9. In the meantime you can visit the repository's admin page and select `gh-pages` as the default branch. How to select the gh-pages as the default branch using GitHub's UI. 10. You can now delete the `master` branch…
git push origin :master
11. …and reset `origin`'s `HEAD`:
git remote set-head origin -a
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.
curl >
        # Change the links inside of the readme file
        git add
        git commit -m "Updated README to link to live spec."
        git push origin
13. Bask in the glory of modern spec development. Publishing releases ------------------- Coming soon.