jsonschema-mdbook-prepare
Overview
In order to publish JSON Schema documentation to a website, we use jsonschema2md to first generate the schema documentation in Markdown, then mdBook to create the human-readable HTML website.
mdBook takes a file, SUMMARY.md, to tell it what markdown files it needs to include, as well as to create a sidebar menu with the table of contents.
jsonschema2md generates a lot of files, including ones for the top-level schemas but also many smaller files for each object and property. Including all of these in SUMMARY.md generates an extremely cluttered TOC menu, however mdBook will only generate HTML files for the Markdown files listed in SUMMARY.md, so only including the top-level schema documents results in lots of broken links.
The solution is to do two passes, one using a SUMMARY.md containing all the files, and a second pass with a tailored SUMMARY.md containing just the top-level schemas, and structured by folder, to generate the desired TOC menu.
After the first pass, we take a copy of the generated HTML files, since mdBook cleans the target folder before each pass. Then after the second pass we copy the additional files created in the first pass back into the final target folder.
There is an additional problem in that the files generated in the first pass contain the cluttered TOC menu with all the files in it, and the menu content is included in every file (i.e. not contained a single shared file), so we need to go through the additional files to replace their menu with the short, structured one generated in the second pass of jsonschema2md.
jsonschema-mdbook-prepare is a CLI program that has two commands, gen-summary and fix-sidebar.
Usage
$ npm install -g jsonschema-mdbook-prepare
$ jsonschema-mdbook-prepare COMMAND
running command...
$ jsonschema-mdbook-prepare (-v|--version|version)
jsonschema-mdbook-prepare/0.1.2 darwin-x64 node-v14.15.3
$ jsonschema-mdbook-prepare --help [COMMAND]
USAGE
$ jsonschema-mdbook-prepare COMMAND
...Commands
jsonschema-mdbook-prepare fix-sidebar
Updates the sidebar menu in html files generated by mdBook by reading it from an index.html file that has the desired menu and replacing the menu in the other files.
USAGE
$ jsonschema-mdbook-prepare fix-sidebar
OPTIONS
-d, --destPath=destPath (required) path-to-destination-folder
-h, --help show CLI help
-s, --sourcePath=sourcePath (required) path-to-source-folder
-v, --version show CLI version
See code: src/commands/fix-sidebar.ts
jsonschema-mdbook-prepare gen-summary
Generates a concise SUMMARY.md for mdbook for content generated using jsonschema2md. Book index will contain just the top level schemas, grouped by folder.
USAGE
$ jsonschema-mdbook-prepare gen-summary
OPTIONS
-a, --allFiles Generate for all .md files, not just top-level schemas
-h, --help show CLI help
-m, --mdPath=mdPath (required) path-to-md-files (generated by jsonschema2md)
-s, --schemaPath=schemaPath (required) path-to-schemas
-v, --version show CLI version
See code: src/commands/gen-summary.ts
jsonschema-mdbook-prepare help [COMMAND]
display help for jsonschema-mdbook-prepare
USAGE
$ jsonschema-mdbook-prepare help [COMMAND]
ARGUMENTS
COMMAND command to show help for
OPTIONS
--all see all commands in CLI
See code: @oclif/plugin-help