Skip to content
master
Switch branches/tags
Go to file
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 
js
 
 
lib
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

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>

About

Open-source documentation for common JSON formats.

Resources

License

Releases

No releases published

Packages

No packages published

Contributors 4

  •  
  •  
  •  
  •