jsonschema-mdbook-prepare

• Overview
• Usage
• Commands

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
• Overview
• Usage
• Commands
  • jsonschema-mdbook-prepare fix-sidebar
  • jsonschema-mdbook-prepare gen-summary
  • jsonschema-mdbook-prepare help [COMMAND]

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