npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

gitbook-plugin-json-schema

v0.1.9

Published

Gitbook plugin to convert JSON schema to markdown documentation

Downloads

13

Readme

Gitbook Plugin: JSON-Schema

code style: prettier Build Status Code Coverage NPM Version Dependancy Status Dev Dependancy Status NPM Downloads

This plugin for Gitbook takes a JSON-Schema and exposes a block that matches ids to autogenerates docs.

Usage

Simply provide an id that exists somewhere in your schema.

{% schema "card" %}
{% endschema %}

The plugin will generate docs that describe the required and optional properties.

Card Docs Example Image

Configuration

Schema

The basic configuration requires only a path to your schema definition or the schema itself.

{
  "plugins": ["json-schema"],
  "pluginsConfig": {
    "json-schema": {
      "schema": "http://json-schema.org/example/card.json"
    }
  }
}

Bundled

To properly parse a schema and generate the docs, this plugin requires the entire schema to be bundled into one file with only internal $ref pointers. When this plugin is in the init phase it will try to bundle the schema by default. If this schema is large it can take quite awhile to bundle it.

To speed up development you might want to pre-bundle your schema with JSON-Schema-Ref-Parser. If you do this you should also state so in your config:

{
  "pluginsConfig": {
    "json-schema": {
      "bundled": true,
      "schema": "./schema/merged_schema.json"
    }
  }
}

Omit Properties

Globally omit properties that are included in all of your schema.

{
  "pluginsConfig": {
    "json-schema": {
      "omitProperties": [
        "names",
        "of",
        "properties",
        "to",
        "exclude",
        "_comment"
      ],
      ...
    }
  }
}

Traverse Objects

Set to true if you want properties that are objects to display their own property list.

{
  "pluginsConfig": {
    "json-schema": {
      "traverseObjects": true,
      ...
    }
  }
}

Plugins

Transform some property in your schema into a more complex UI component. To do this you can map the property key (or path to the key) to a render function. Top level property keys are omitted from the required and optional lists.

Note: The plugin code must be ES5.

{
  "pluginsConfig": {
    "json-schema": {
      "plugins": {
        "modifiers": "./path/to/es5/plugin/modifierTable.js",
        "metaData.properties.role": "./path/to/es5/plugin/roleTable.js"
      },
      ...
    }
  }
}

Example Plugin

const roleRow = schema => `
    <tr>
      <td>${schema.const}</td>
      <td>${schema.description}</td>
    </tr>
  `;

const roleTable = ({ oneOf }) => {
  if (!oneOf) return '';

  return `
    <h4>Role</h4>
    <table>
      <thead>
        <tr>
          <td>Role</td>
          <td>Description</td>
        </tr>
      </thead>
      <tbody>
        ${oneOf.map(roleRow).join('')}
      </tbody>
    </table>
  `;
};

export default roleTable;

Which generates:

Plugin Example

Releasing

Run the release script with new version number (e.g 1.1.0)

npm run release -- 1.1.0

Mark each commit as either patch, minor or major. A tag is then created for the release, release notes are generated, and a release is published to github.

Contributing / Bug Reporting

I built this to work with simple schemas and a very complex specific schema, so there might be patterns that aren't covered by the plugin. For these cases please file an Issue or a Pull Request.