JSON

The json generator emits a single JSON document containing every symbol Mr.Docs extracted. It’s the same data the Handlebars templates render from, serialized straight to JSON. Like XML, it’s an intermediate format: not meant to be read as documentation, but easy to consume from any language with a JSON parser. Pick it explicitly through the generator option:

generator: json

The most common reasons to use it are:

Rendering the documentation yourself: feed the JSON to your own template engine or static-site pipeline instead of the built-in generators.
Post-processing the corpus from a language where JSON is the path of least resistance (JavaScript, Python, Go), without an XML parser or XSLT.
Debugging templates: dump the exact object graph a template sees so you can inspect a field’s shape before writing the Handlebars for it.

Output

The output is a single file (reference.json by default) regardless of the multipage setting; multipage is meaningful only for the text generators. The document is an object with a symbols array; the generator walks the corpus one symbol at a time and appends each symbol’s DOM.

For example, this input:

/// A widget.
struct Widget {};

with this configuration:

generator: json
generator-options:
  json:
    emit-empty: false

produces (the emit-empty: false above drops empty fields, keeping the example compact):

{
    "symbols": [
        {
            "anchor": "index",
            "kind": "namespace",
            "id": "4ZrjxJnU1LA5xSyrWMNuXTvSYKwt",
            "extraction": "regular",
            "members": {
                "records": [
                    "4STgDrwLeHv7mqV5anD6cJEd6K4T"
                ]
            }
        },
        {
            "name": "Widget",
            "anchor": "Widget",
            "loc": {
                "defLoc": {
                    "shortPath": "example.cpp",
                    "sourcePath": "example.cpp",
                    "lineNumber": 2,
                    "columnNumber": 1,
                    "documented": true
                }
            },
            "kind": "record",
            "id": "4STgDrwLeHv7mqV5anD6cJEd6K4T",
            "extraction": "regular",
            "parent": "4ZrjxJnU1LA5xSyrWMNuXTvSYKwt",
            "doc": {
                "brief": {
                    "kind": "brief",
                    "children": [
                        {
                            "kind": "text",
                            "literal": "A widget."
                        }
                    ]
                }
            },
            "keyKind": "struct"
        }
    ]
}

Symbols are emitted flat in the symbols array; parent/child relationships are expressed through id references (the base58 strings above) rather than nesting, exactly as in the XML output. To walk from one symbol to another, index the array by id.

Options

The generator reads two options from generator-options under the json key:

generator: json
generator-options:
  json:
    include-meta: false
    emit-empty: true

include-meta: each object in the DOM carries a $meta field ({ "type": …, "bases": […] }) describing the reflected C++ type it came from. It’s on the object the templates see, but it’s usually noise for an external consumer, so the generator drops it by default. Set include-meta: true to keep it.
emit-empty: on by default, so the output is complete. Set it to false to drop empty fields and array elements, using the same rule as Handlebars: empty strings, empty arrays, empty objects, null, and false are dropped, but numbers (including 0) are kept.

Schema

The JSON mirrors the DOM one-to-one: every field is named exactly as the DOM reference documents it, since the generator serializes that DOM directly. A field shown as members in the DOM is a members key here, loc is loc, and so on. Values follow JSON types: strings, numbers, booleans, arrays, and nested objects.

Rolling your own with a script

This built-in is a convenience. The corpus reaches a script as plain data too, so the same output is a few lines of JavaScript through a script-driven generator: JSON.stringify(ctx.corpus.symbols) serializes it directly. Reach for a script when you want to reshape the JSON, filter symbols, or wire up your own options; a script generator registered under json even replaces this built-in. The JSON example under corpus extensions shows the whole thing.