Open-source documentation for common JSON formats.
JavaScript CoffeeScript CSS HTML
Switch branches/tags
Nothing to show
Clone or download
zackbloom Merge pull request #5 from cameron/hide-tour-across-subdomains
persist "hide tour" click across subdomains
Latest commit 44abd12 Aug 10, 2016

README.md

JSON.is

Open-source documentation for common JSON formats.

Currently included:

Contributing

We welcome contributors of both improvements and additional JSON formats.

Format

Format definition files are located in coffee/formats.

The definitions are CoffeeScript source files. Each file exports an object mapping regular expressions to HTML descriptions. The regular expressions are tested against the path to the object the user currently has his or her cursor over. The first complete match determines what documentation block is shown.

For example, to add a doc for {"engines": ...}, you would specify:

'engines': '''
  <h4>Engines</h4>
'''

Any character with special meaning in regular expressions (like [ and .) should be escaped with a backslash:

'engines\.node': '''
  <h4>Node Version</h4>
'''

There are two 'shortcuts' which are available, INDEX and PROPERTY.

  • INDEX (\d+) matches any index within an array
  • PROPERTY ([^\.]+) matches any key within an object

For example, to write a doc for any property within engines:

'engines\.PROPERTY': '''
  <h4>Engines</h4>
'''

You can use regular expression syntax to create a section which will match both the parent, and it's children:

'engines(\.PROPERTY)?': '''
  <h4>Engines</h4>
'''

When dealing with an array, you can do a similar thing with INDEX:

'keywords\.INDEX': '''
  <h4>Keyword</h4>
'''

You can use the pipe regular expression syntax to match multiple options:

'(dependencies|devDependencies)': '''
  <h4>Dependencies</h4>
'''

As each file is CoffeeScript, you can add arbitrary code:

'description': '''
  <h4>Description</h4>
''' + new Date

Each doc body can also be a function, which will be passed the item which was matched:

'(dependencies|devDependencies)': (item) ->
  "<h4>#{ item.path }</h4>"

HTML Conventions

  • Begin each doc with a title in an h4.
  • Wrap each paragraph in a p.
  • Docs can optionally begin with a subtitle wrapped like <p><em>Subtitle</em></p>
  • Inline code blocks should be wrapped with a code element
  • Block code blocks should be wrapped like <pre><code>my code</code></pre>