GitHub API documentation
Ruby CSS JavaScript Shell
Pull request Compare This branch is 3152 commits behind github-archive:master.
Failed to load latest commit information.
content Sync changes from upstream repository Aug 26, 2014
layouts Sync changes from upstream repository Aug 26, 2014
lib Sync changes from upstream repository Aug 19, 2014
script Sync upstream changes Aug 12, 2014
.gitattributes Move static resources around, adding new datasource to handle them Aug 6, 2011
.gitignore Add HTML::Proofer tests Feb 12, 2014
.rvmrc Make rvm use 1.9.3. Jun 24, 2012
.travis.yml Stick to just 1.9.3, Travis Feb 12, 2014
CNAME developers developers developers developers developers developers dev… Apr 28, 2011
Gemfile.lock Sync upstream changes Aug 12, 2014
Guardfile Sync changes from upstream repository Aug 6, 2014 Sync changes from upstream repository May 22, 2014
Rakefile Force checkout of origin/ on Heroku Jun 10, 2014
Rules Sync changes from upstream repository Aug 6, 2014
changes.atom P U B L I S H 📎 Jan 29, 2014
config.yaml setup api transition summaries. beta => v3 Sep 5, 2012
favicon.ico Merge pull request #243 from github/identity-next Apr 16, 2013

This is a GitHub API resource built with nanoc.

All submissions are welcome. To submit a change, fork this repo, commit your changes, and send us a pull request.


Ruby 1.9 is required to build the site.

Get the nanoc gem, plus kramdown for Markdown parsing:

$ bundle install

You can see the available commands with nanoc:

$ bundle exec nanoc -h

Nanoc has some nice documentation to get you started. Though if you're mainly concerned with editing or adding content, you won't need to know much about nanoc.


Not sure how to structure the docs? Here's what the structure of the API docs should look like:

# API title


## API endpoint title

    [VERB] /path/to/endpoint

### Parameters

Name | Type | Description
`name`|`type` | Description.

### Input (request JSON body)

Name | Type | Description
`name`|`type` | Description.

### Response

<%= headers 200, :pagination => default_pagination_rels, 'X-Custom-Header' => "value" %>
<%= json :resource_name %>

Note: We're using Kramdown Markdown extensions, such as definition lists.

JSON Responses

We specify the JSON responses in Ruby so that we don't have to write them by hand all over the docs. You can render the JSON for a resource like this:

<%= json :issue %>

This looks up GitHub::Resources::ISSUE in lib/resources.rb.

Some actions return arrays. You can modify the JSON by passing a block:

<%= json(:issue) { |hash| [hash] } %>

Terminal blocks

You can specify terminal blocks with pre.terminal elements. (It'd be nice if Markdown could do this more cleanly.)

<pre class="terminal">
$ curl foobar

This is not a curl tutorial though. Not every API call needs to show how to access it with curl.


Nanoc compiles the site into static files living in ./output. It's smart enough not to try to compile unchanged files:

$ bundle exec nanoc compile
Loading site data...
Compiling site...
   identical  [0.00s]  output/css/960.css
   identical  [0.00s]  output/css/pygments.css
   identical  [0.00s]  output/css/reset.css
   identical  [0.00s]  output/css/styles.css
   identical  [0.00s]  output/css/uv_active4d.css
      update  [0.28s]  output/index.html
      update  [1.31s]  output/v3/gists/comments/index.html
      update  [1.92s]  output/v3/gists/index.html
      update  [0.25s]  output/v3/issues/comments/index.html
      update  [0.99s]  output/v3/issues/labels/index.html
      update  [0.49s]  output/v3/issues/milestones/index.html
      update  [0.50s]  output/v3/issues/index.html
      update  [0.05s]  output/v3/index.html

Site compiled in 5.81s.

You can setup whatever you want to view the files. If using the adsf gem (as listed in the Gemfile), you can start Webrick:

$ bundle exec nanoc view
$ open http://localhost:3000

Compilation times got you down? Use autocompile!

$ bundle exec nanoc autocompile

This starts a web server too, so there's no need to run nanoc view. One thing: remember to add trailing slashes to all nanoc links!


$ bundle exec rake publish