Generators

A generator turns the extracted symbol corpus into rendered documentation. Mr.Docs ships three built-in formats:

Format	When to pick it
HTML	The default. Self-contained pages with a bundled stylesheet, ready to serve from any static host. Pick this for a documentation site without an outer build pipeline.
AsciiDoc	Source for AsciiDoc tooling and Antora documentation. Pick this when the reference is folded into a larger documentation site, or when you want full control over the final HTML through Asciidoctor.
XML	Structured intermediate format. Pick this when a downstream tool wants every symbol field, when you want to diff the corpus across releases, or when you’re testing the corpus shape directly.

Format

When to pick it

The default. Self-contained pages with a bundled stylesheet, ready to serve from any static host. Pick this for a documentation site without an outer build pipeline.

AsciiDoc

Source for AsciiDoc tooling and Antora documentation. Pick this when the reference is folded into a larger documentation site, or when you want full control over the final HTML through Asciidoctor.

XML

Structured intermediate format. Pick this when a downstream tool wants every symbol field, when you want to diff the corpus across releases, or when you’re testing the corpus shape directly.

Defining a new output format via Data-Driven Generators is also very cheap. The repository includes a few ready-to-use starting points:

Markdown: GitHub-Flavored Markdown with HTML fallback for the cases GFM cannot express.
LaTeX: article-class LaTeX with tabular tables.
JSON Lines: One JSON object per symbol for a search index.

Pick one through the generator option:

generator: html

Or on the command line, where the flag wins over the file:

mrdocs --config=path/to/mrdocs.yml --generator=html

Choosing between formats

Each format trades redundancy (how much duplicated or unstructured information lives in the output) against convenience (how readily the output is usable without further tooling).

quadrantChart title Output format trade-off x-axis Low redundancy --> High redundancy y-axis Low convenience --> High convenience Ideal: [0.04, 0.96] radius: 4, color: #cccccc, stroke-color: #cccccc, stroke-width: 1px HTML: [0.88, 0.94] AsciiDoc: [0.78, 0.78] Custom Templates: [0.5, 0.6] Data-Driven Generators: [0.36, 0.5] Custom Generators: [0.2, 0.3] XML: [0.05, 0.12] Clang AST: [0.88, 0.06] radius: 5, color: #f1c7c7, stroke-color: #f1c7c7, stroke-width: 1px

AsciiDoc and HTML cluster in the top-right: high convenience (Antora consumes the AsciiDoc natively, the HTML opens straight in a browser) at the cost of more structural overhead per symbol.
Custom Templates let you sit anywhere along the diagonal without leaving the built-in formats: keep the html or adoc generator and write the Handlebars overrides that move the trade-off to where your project needs it.
Data-Driven Generators sit close to Custom Templates on the chart: the same Handlebars machinery, but pointed at a new output format declared by a manifest (Markdown, RST, anything else you want a generator for) instead of customizing the built-in html or adoc output.
Custom Generators go further down toward XML: a generator implemented entirely in code (C++ or a script), with full control over the bytes it writes. Useful when the format you need does not fit a Handlebars-and-manifest description, at the cost of being the most work to build and maintain.
XML sits in the bottom-left: low redundancy (one terse element per field) and low convenience for direct consumption. The right choice when a downstream tool wants every symbol field.
Clang AST (bottom-right) and the Ideal marker (top-left) frame the chart, neither is something Mr.Docs ships. The AST is what Mr.Docs reads, dense but unworkable on its own. The Ideal point is the theoretical "low redundancy and high convenience" target no single format reaches.