Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/cloudflare/json.is
Open-source documentation for common JSON formats.
https://github.com/cloudflare/json.is
Last synced: about 1 month ago
JSON representation
Open-source documentation for common JSON formats.
- Host: GitHub
- URL: https://github.com/cloudflare/json.is
- Owner: cloudflare
- License: mit
- Created: 2015-06-22T19:15:55.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2023-03-21T13:25:25.000Z (over 1 year ago)
- Last Synced: 2024-04-14T22:17:09.427Z (7 months ago)
- Language: JavaScript
- Homepage: http://json.is
- Size: 149 KB
- Stars: 302
- Watchers: 19
- Forks: 43
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# JSON.is
Open-source documentation for common JSON formats.
Currently included:
- [bower.json.is](http://bower.json.is) — `bower.json` documentation
- [install.json.is](http://install.json.is) — `install.json` documentation
- [package.json.is](http://package.json.is) — `package.json` documentation
## Contributing
We welcome contributors of both improvements and additional JSON formats.
### Format
Format definition files are located in [coffee/formats](https://github.com/EagerIO/JSON.is/tree/master/coffee/formats).
The definitions are [CoffeeScript](http://coffeescript.org/) source files. Each file exports an
object mapping [regular expressions](http://www.cheatography.com/davechild/cheat-sheets/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:
```coffeescript
'engines': '''
Engines
'''
```
Any character with special meaning in regular expressions (like `[` and `.`) should be escaped with a backslash:
```coffeescript
'engines\.node': '''
Node Version
'''
```
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`:
```coffeescript
'engines\.PROPERTY': '''
Engines
'''
```
You can use regular expression syntax to create a section which will match both the parent, and it's children:
```coffeescript
'engines(\.PROPERTY)?': '''
Engines
'''
```
When dealing with an array, you can do a similar thing with `INDEX`:
```coffeescript
'keywords\.INDEX': '''
Keyword
'''
```
You can use the pipe regular expression syntax to match multiple options:
```coffeescript
'(dependencies|devDependencies)': '''
Dependencies
'''
```
As each file is CoffeeScript, you can add arbitrary code:
```coffeescript
'description': '''
Description
''' + new Date
```
Each doc body can also be a function, which will be passed the item which was matched:
```coffeescript
'(dependencies|devDependencies)': (item) ->
"
#{ item.path }
"
```
#### 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 `
Subtitle
`
- Inline code blocks should be wrapped with a `code` element
- Block code blocks should be wrapped like `my code
`