Output
MrDocs separates corpus extraction (everything covered by Filters and Extraction) from the presentation layer that renders the corpus to disk. The options on this page belong to that second half: they pick the output format, decide what is visible on the rendered pages, link those pages to the source code and to other documentation sets, and let you swap or extend the styling. The Output reference lists every option with its default and an example.
Format
generator picks the format MrDocs emits. The built-in choices are html (the default), adoc, and xml; the Generators section describes what each produces and when to choose it.
/// Multiply two integers.
int multiply(int a, int b);mrdocs.ymlgenerator: adocmultiply
Multiply two integers.
Synopsis
Declared in <generator.cpp>
int
multiply(
int a,
int b);output is the directory (or, for a single-file generator, the file) MrDocs writes to. The default is <config-dir>/reference-output. It’s very common to override this option in the site’s pages directory from the CLI. MrDocs creates the directory if it does not exist.
multipage (on by default) writes one file per symbol so the result can be browsed page-by-page on a website. Turn it off for a one-shot dump or when the output will be embedded in a larger single document.
Showing and hiding
The options here change what the presentation layer renders without changing what is in the corpus.
show-namespaces (on by default) gives each namespace its own page. Turn it off for a flatter, easier-to-skim layout in which namespaces are collapsed into the parent’s listing:
/// A tiny example library.
///
/// Holds the entry points the documentation calls out
/// and a few helpers consumed by the rest of the project.
namespace lib {
/// A function inside `lib`. With `show-namespaces: true`
/// the namespace appears in the rendered output as a
/// dedicated entry; with `false` the namespace is
/// flattened into the parent.
void run();
}mrdocs.ymlshow-namespaces: trueGlobal namespace
Namespaces
Name |
Description |
A tiny example library. |
lib
A tiny example library.
Description
Holds the entry points the documentation calls out and a few helpers consumed by the rest of the project.
Functions
Name |
Description |
A function inside |
lib::run
A function inside lib. With show‐namespaces: true the namespace appears in the rendered output as a dedicated entry; with false the namespace is flattened into the parent.
Synopsis
Declared in <show‐namespaces.cpp>
void
run();show-enum-constants gives each enumerator its own page, with its full description visible there (and the link from the enum’s synopsis pointing at that page):
/// Status of a network operation.
enum class status
{
/// Operation succeeded.
ok,
/// Operation timed out.
timeout,
/// Operation failed for another reason.
error,
};mrdocs.ymlshow-enum-constants: truestatus
Status of a network operation.
Synopsis
Declared in <show‐enum‐constants.cpp>
enum class status : int;Members
Name |
Description |
Operation succeeded. |
|
Operation timed out. |
|
Operation failed for another reason. |
status::ok
Operation succeeded.
Synopsis
Declared in <show‐enum‐constants.cpp>
okstatus::timeout
Operation timed out.
Synopsis
Declared in <show‐enum‐constants.cpp>
timeoutstatus::error
Operation failed for another reason.
Synopsis
Declared in <show‐enum‐constants.cpp>
error
When show-enum-constants is off (the default), enumerators are folded into the enum’s synopsis and only their brief sentence travels with them (in the default generator templates). Any detailed description, @par blocks, `@note`s, or other metadata you wrote on the enumerators are dropped from the rendered output, because there is no enumerator-specific page to host them. If you wrote long-form documentation on an enumerator, turn the option on so that documentation has somewhere to live.
|
global-namespace-index turns the global-namespace page into a project-wide index of every top-level symbol. legible-names uses readable symbol names in file names and URLs (the alternative is short opaque hashes).
Source links
base-url is the prefix MrDocs joins with each source file’s path to build the "Declared in" link. Set it to your repository’s blob URL so every symbol page links to the code that defines it:
/** Compute the area of a circle of radius `r`. */
double area(double r);mrdocs.ymlbase-url: https://github.com/example/geom/blob/main/area
Compute the area of a circle of radius r.
Synopsis
Declared in <base‐url.cpp>
double
area(double r);External docs
tagfile writes a Doxygen-compatible tag file alongside the documentation. The expected use is cross-linking: other MrDocs runs can read it to resolve @ref targets that live in your library, and Doxygen-generated docs can consume it for the same purpose. Reach for it when you publish a library that other people’s docs need to link to.
| A few projects use the tag file in a less obvious way: they read it from their own site-generation scripts to build a navigation tree or a search index from the symbol list, rather than maintaining one by hand. |
The inverse direction (consuming tag files emitted by other projects so that your pages link to their symbols) is handled by the antora-cpp-tagfiles-extension. Point it at one or more tag files in your Antora playbook, and references like boost::asio::io_context resolve to the Boost.Asio site automatically.
|
Styling
The default HTML output ships with a stylesheet that is fine to publish as-is. The options here come into play when you want the pages to match the rest of a site, or when you need to swap the markup outright for something the built-in template cannot produce.
stylesheets adds extra stylesheets to every HTML page. no-default-styles drops the built-in stylesheet entirely (because you are shipping your own). linkcss and copycss decide whether each stylesheet is referenced by <link> or copied next to the output, and stylesdir sets the directory the href attributes point at.
When you need to change the markup itself (not just the styles), reach for Handlebars templates and the addons / addons-supplemental options that load them.
embedded drops the page wrapper (header, sidebar, footer) from the HTML output so the symbol pages can be embedded inside another document. Reach for it when MrDocs is rendering snippets into a larger site rather than producing a standalone manual.