{"id":15522499,"url":"https://github.com/hipstersmoothie/gitbook-plugin-json-schema","last_synced_at":"2025-03-28T20:16:26.047Z","repository":{"id":66130505,"uuid":"129813749","full_name":"hipstersmoothie/gitbook-plugin-json-schema","owner":"hipstersmoothie","description":"A plugin for Gitbook takes a JSON-Schema and exposes a block that matches ids to autogenerates docs.","archived":false,"fork":false,"pushed_at":"2018-06-06T02:27:33.000Z","size":354,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-03T12:47:53.778Z","etag":null,"topics":["auto","autodoc","block","documentation","documentation-tool","gitbook","gitbook-plugin","id","json","json-schema","schema"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hipstersmoothie.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-04-16T22:31:28.000Z","updated_at":"2025-02-19T13:31:02.000Z","dependencies_parsed_at":"2023-02-20T16:46:07.593Z","dependency_job_id":null,"html_url":"https://github.com/hipstersmoothie/gitbook-plugin-json-schema","commit_stats":{"total_commits":88,"total_committers":4,"mean_commits":22.0,"dds":"0.19318181818181823","last_synced_commit":"0c800ac0bf783c84389f8d6493531fbdd87bf3ff"},"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hipstersmoothie%2Fgitbook-plugin-json-schema","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hipstersmoothie%2Fgitbook-plugin-json-schema/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hipstersmoothie%2Fgitbook-plugin-json-schema/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hipstersmoothie%2Fgitbook-plugin-json-schema/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hipstersmoothie","download_url":"https://codeload.github.com/hipstersmoothie/gitbook-plugin-json-schema/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246093179,"owners_count":20722403,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["auto","autodoc","block","documentation","documentation-tool","gitbook","gitbook-plugin","id","json","json-schema","schema"],"created_at":"2024-10-02T10:41:21.319Z","updated_at":"2025-03-28T20:16:26.026Z","avatar_url":"https://github.com/hipstersmoothie.png","language":"JavaScript","readme":"# Gitbook Plugin: JSON-Schema\n\n[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=for-the-badge)](https://github.com/prettier/prettier)\n[![Build Status](https://img.shields.io/circleci/project/github/hipstersmoothie/gitbook-plugin-json-schema/master.svg?style=for-the-badge)](https://circleci.com/gh/hipstersmoothie/gitbook-plugin-json-schema/tree/master)\n[![Code Coverage](https://img.shields.io/codecov/c/github/hipstersmoothie/gitbook-plugin-json-schema/master.svg?style=for-the-badge)](https://codecov.io/gh/hipstersmoothie/gitbook-plugin-json-schema)\n[![NPM Version](https://img.shields.io/npm/v/gitbook-plugin-json-schema.svg?style=for-the-badge)](https://www.npmjs.com/package/gitbook-plugin-json-schema) ![Dependancy Status](https://img.shields.io/david/hipstersmoothie/gitbook-plugin-json-schema.svg?style=for-the-badge) ![Dev Dependancy Status](https://img.shields.io/david/dev/hipstersmoothie/gitbook-plugin-json-schema.svg?style=for-the-badge)\n[![NPM Downloads](https://img.shields.io/npm/dt/gitbook-plugin-json-schema.svg?style=for-the-badge)](https://www.npmjs.com/package/gitbook-plugin-json-schema)\n\nThis plugin for [Gitbook](https://github.com/GitbookIO/gitbook) takes a [JSON-Schema](http://json-schema.org/) and exposes a [block](https://toolchain.gitbook.com/plugins/blocks.html) that matches [ids](http://json-schema.org/latest/json-schema-core.html#id-keyword) to autogenerates docs.\n\n## Usage\n\nSimply provide an id that exists somewhere in your schema.\n\n```md\n{% schema \"card\" %}\n{% endschema %}\n```\n\nThe plugin will generate docs that describe the required and optional properties.\n\n![Card Docs Example Image](https://raw.githubusercontent.com/hipstersmoothie/gitbook-plugin-json-schema/master/images/cardDocs.png)\n\n## Configuration\n\n### Schema\n\nThe basic configuration requires only a path to your schema definition or the schema itself.\n\n```json\n{\n  \"plugins\": [\"json-schema\"],\n  \"pluginsConfig\": {\n    \"json-schema\": {\n      \"schema\": \"http://json-schema.org/example/card.json\"\n    }\n  }\n}\n```\n\n### Bundled\n\nTo 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.\n\nTo speed up development you might want to pre-bundle your schema with [JSON-Schema-Ref-Parser](https://github.com/BigstickCarpet/json-schema-ref-parser). If you do this you should also state so in your config:\n\n```json\n{\n  \"pluginsConfig\": {\n    \"json-schema\": {\n      \"bundled\": true,\n      \"schema\": \"./schema/merged_schema.json\"\n    }\n  }\n}\n```\n\n### Omit Properties\n\nGlobally omit properties that are included in all of your schema.\n\n```json\n{\n  \"pluginsConfig\": {\n    \"json-schema\": {\n      \"omitProperties\": [\n        \"names\",\n        \"of\",\n        \"properties\",\n        \"to\",\n        \"exclude\",\n        \"_comment\"\n      ],\n      ...\n    }\n  }\n}\n```\n\n### Traverse Objects\n\nSet to true if you want properties that are objects to display their own property list.\n\n```json\n{\n  \"pluginsConfig\": {\n    \"json-schema\": {\n      \"traverseObjects\": true,\n      ...\n    }\n  }\n}\n```\n\n### Plugins\n\nTransform 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.\n\n**_Note: The plugin code must be ES5._**\n\n```json\n{\n  \"pluginsConfig\": {\n    \"json-schema\": {\n      \"plugins\": {\n        \"modifiers\": \"./path/to/es5/plugin/modifierTable.js\",\n        \"metaData.properties.role\": \"./path/to/es5/plugin/roleTable.js\"\n      },\n      ...\n    }\n  }\n}\n```\n\nExample Plugin\n\n```js\nconst roleRow = schema =\u003e `\n    \u003ctr\u003e\n      \u003ctd\u003e${schema.const}\u003c/td\u003e\n      \u003ctd\u003e${schema.description}\u003c/td\u003e\n    \u003c/tr\u003e\n  `;\n\nconst roleTable = ({ oneOf }) =\u003e {\n  if (!oneOf) return '';\n\n  return `\n    \u003ch4\u003eRole\u003c/h4\u003e\n    \u003ctable\u003e\n      \u003cthead\u003e\n        \u003ctr\u003e\n          \u003ctd\u003eRole\u003c/td\u003e\n          \u003ctd\u003eDescription\u003c/td\u003e\n        \u003c/tr\u003e\n      \u003c/thead\u003e\n      \u003ctbody\u003e\n        ${oneOf.map(roleRow).join('')}\n      \u003c/tbody\u003e\n    \u003c/table\u003e\n  `;\n};\n\nexport default roleTable;\n```\n\nWhich generates:\n\n![Plugin Example](https://raw.githubusercontent.com/hipstersmoothie/gitbook-plugin-json-schema/master/images/pluginExample.png)\n\n# Releasing\n\nRun the `release` script with new version number (e.g 1.1.0)\n\n```\nnpm run release -- 1.1.0\n```\n\nMark 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.\n\n# Contributing / Bug Reporting\n\nI 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](https://github.com/hipstersmoothie/gitbook-plugin-json-schema/issues) or a [Pull Request](https://github.com/hipstersmoothie/gitbook-plugin-json-schema/pulls).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhipstersmoothie%2Fgitbook-plugin-json-schema","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhipstersmoothie%2Fgitbook-plugin-json-schema","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhipstersmoothie%2Fgitbook-plugin-json-schema/lists"}