Diagnostics

These options govern what MrDocs reports while it runs and how it behaves when something goes wrong. They change what appears in your terminal, not the documentation itself, so there is no rendered example below. The Diagnostics reference has the full option list.

Doc-comment lint

The warn-* family treats common documentation problems as warnings, so a CI run can catch them the same way it catches compiler warnings. The most useful ones in practice:

warn-as-error turns every warning into a failure, the usual CI setup once a project is past the bring-up phase.

For large third-party trees (LLVM-scale), turn categories on gradually and cap each fix-loop round with max-errors, which works like a compiler’s -fmax-errors. It only takes effect with warn-as-error.

warnings: true
warn-if-undocumented: true
warn-if-doc-error: true
warn-broken-ref: true
warn-as-error: false
# Optional bring-up cap (needs warn-as-error); leave at 0 (or omit) for full CI reports.
# max-errors: 40
Pair warn-as-error with max-errors (for example 40) and the warn-if-undocumented family while you fill in comments. Each run fails fast with a small batch; knock that batch out, rerun, and repeat until the build goes green with max-errors: 0.

warnings is the master switch: set it to false to silence the entire family at once.

Log verbosity

log-level picks the verbosity (error, warn, info, debug, trace). verbose is the boolean shorthand for the most detailed level.

log-level: info
verbose: false

Runtime tuning

concurrency caps the number of threads MrDocs uses to extract symbols. The default 0 matches the hardware; lower it on shared CI runners or to make logs easier to read.

concurrency: 4