Asciidoctor vs JSON Schema for Humans
Asciidoctor
asciidoctor.orgJSON Schema for Humans
json-schema-for-humans.readthedocs.ioSide by side
| Figure | Asciidoctor | JSON Schema for Humans |
|---|---|---|
| Price from | Free | Free |
| Free plan | Yes | Yes |
| Free trial | — | — |
| Open source | — | — |
| Web | Yes | — |
| Windows | Yes | Yes |
| macOS | Yes | Yes |
| Linux | Yes | Yes |
| API | Yes | — |
| Self-hosted | Yes | Yes |
| Plans published | 1 | 1 |
| Spec score · Documentation Generators | 8.9 (#1) | 8.6 (#3) |
| Integrations | The project ecosystem includes Maven and Gradle plugins, browser extensions, an IntelliJ plugin, and tools such as Asciidoctor Diagram. | A `techdocs` template is described as optimized for TechDocs and MkDocs Material. |
| License | The processor is open source software available under the MIT license. | The project is licensed under Apache License 2.0. |
| Output formats | The core processor includes HTML 5, DocBook 5 and man page converters; PDF and EPUB 3 converters are provided separately. | It supports HTML and Markdown output, with multiple built-in templates. |
| Purpose | Asciidoctor parses AsciiDoc source and converts it into publishable formats such as HTML 5 and PDF. | The project generates static HTML or Markdown pages documenting JSON Schema. |
| Support | The documentation directs users seeking real-time community support to the project chat’s #users stream. | The project README invites contributions and directs users to its contributing guide. |
Plans
In their own words
Asciidoctor
Asciidoctor is a free, open-source text processor and publishing toolchain for converting AsciiDoc files or strings into formats such as HTML5, DocBook, PDF, EPUB 3 and manual pages. Its core includes converters for HTML5, DocBook 5 and man pages; PDF and EPUB 3 conversion comes from separate gems. Documents can be processed through a command-line interface or Ruby API. Asciidoctor runs with Ruby, on the JVM through AsciidoctorJ, or in JavaScript environments through Asciidoctor.js, and supports Linux, macOS and Windows. The wider ecosystem includes Maven and Gradle plugins, browser and editor extensions, and diagram tools. Default HTML output includes a stylesheet and integrations such as Font Awesome, highlight.js, Rouge, Pygments and MathJax. It is distributed as a RubyGem, Docker image, Linux packages and macOS packages, and is licensed under MIT. Its security modes include SECURE, SAFE, SERVER and UNSAFE; safe modes do not sanitize generated output or provide a comprehensive security framework.
JSON Schema for Humans
JSON Schema for Humans generates static HTML or Markdown documentation from valid JSON Schema files. Inputs can be JSON or YAML, supplied to its command-line interface as a file, directory, glob pattern, or comma-separated list; Python methods are also available. Multiple templates produce different outputs. The default JavaScript template provides expandable sections, tabs for conditional subschemas, and anchor links. The js_offline template bundles CSS and JavaScript for offline viewing. Markdown output can be published without an HTTP server and is rendered by GitHub when browsing code. A techdocs template is described as optimized for TechDocs and MkDocs Material. References can point within a schema, to local files, or to URLs, including circular references, and the project lists JSON Schema Draft-07 support. Safe mode escapes HTML tags in descriptions by default, while configuration can allow HTML. Property names and size, property dependencies, and media are listed as unsupported. The Apache-2.0 licensed package documents installation with `pip install json-schema-for-humans`.