Using GitHub for Spec Work

  1. Create a new GitHub repository using ash-nazg. The spec's shortname in lowercase is usually a good choice.

  2. Once the new repository is created, find it on GitHub and set up GitHub Pages to use the default branch, master (Settings / Options / GitHub Pages).

    GitHub Pages settings of a repository

    The repository's contents will get automagically served from https://username.github.com/reponame.

  3. Clone the repository locally.

    git clone https://github.com/tobie/specs-on-github.git
  4. Navigate to the repo.

    cd 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 index.html page at the root of my repository.

    curl https://www.w3.org/respec/examples/template.html > 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 master

    The first time you push changes it can take a little while for the code to be published to your subdomain, so be patient. But it'll be ready soon enough.

  8. Edit the boilerplate files.

    In particular, you may want to replace the license, picking a different pair of documents (LICENSE.md and CONTRIBUTING.md) from github.com/w3c/licenses. Review the files README.md and w3c.json, too.

  9. Setup your favorite labels

  10. Bask in the glory of modern spec development.