Configuration

MrDocs is configured by options that name the source root, the compilation database, the generator, the filters, and so on. Every option has a YAML key in mrdocs.yml and a kebab-case command-line flag with the same name. The two surfaces are equivalent: pick whichever fits each option, mix them in the same invocation, and the CLI value wins on collision.

A minimal mrdocs.yml

The smallest useful mrdocs.yml points at the source tree and tells MrDocs how to compile it. For a CMake project, that is two lines:

docs/mrdocs.yml
source-root: ..
compilation-database: ../CMakeLists.txt

source-root is the root of your source tree, resolved relative to the mrdocs.yml file. compilation-database tells MrDocs how to compile the sources.

Basic Usage Patterns walks through complete starter projects for each compilation-database shape (existing compile_commands.json, MrDocs-driven CMake, header scan). Pick the one closest to your project and copy it.

From here the file grows as you customize more: a different generator, filters over what gets documented, output options for page structure and styling, and so on. For example, this file produces XML output and limits extraction to the mylib namespace:

docs/mrdocs.yml
source-root: ..
compilation-database: ../CMakeLists.txt
generator: xml
include-symbols:
  - 'mylib::**'

Each category page introduces its options in context, and the Reference lists every option with its default and an example.

Running MrDocs

The commands below assume mrdocs is on your PATH.

The simplest invocation names the config file with the --config flag:

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

If you run MrDocs from the directory that contains mrdocs.yml, you can omit the flag and let the config default take over (it points at mrdocs.yml in the current directory):

mrdocs
--config is the only option that can’t be set in the file, for the obvious reason that a file can’t point at itself. Every other option is mirrored on both surfaces.

CLI overrides

Any option from the config file can be overridden by passing the same name as a CLI flag; the CLI value wins. The example below keeps everything from mrdocs.yml except the output directory:

mrdocs --config=path/to/mrdocs.yml --output=../docs/reference
Relative paths are resolved against the directory containing mrdocs.yml, whether they come from the config file or from the command line. The path to mrdocs.yml itself is the only exception; it is resolved against the shell’s current directory.

File location

mrdocs.yml can sit anywhere. By convention, many projects keep it at docs/mrdocs.yml so the docs/ directory groups everything documentation-related in one place:

A typical layout with docs/mrdocs.yml
+ <project-directory>
  + docs
    + mrdocs.yml
    + ...
  + include
  + src
  + test
  + ...

Wherever the file lives, the most important option to set is source-root. It is the base MrDocs uses to form the per-file paths that link each symbol back to its source file, so combined with base-url it produces working links to the code on your repository host. The default is the directory containing mrdocs.yml, so a mrdocs.yml at the project root needs nothing set; a mrdocs.yml at docs/mrdocs.yml typically uses source-root: .. so the resulting paths are anchored at the repository root.

JSON schema

A JSON schema for mrdocs.yml is published on https://www.schemastore.org/json/, so most editors (including JetBrains IDEs and VS Code) pick it up automatically and start autocompleting option names. To pin a specific schema version, or to bind the schema manually in an editor that does not consult Schema Store, prepend a directive at the top of the file:

  • JetBrains IDEs honor # $schema: <url>.

  • Editors backed by the YAML language server honor # yaml-language-server: $schema=<url>.

Inline-schema file compatible with both editors
# $schema: https://mrdocs.com/docs/mrdocs/develop/_attachments/mrdocs.schema.json
# yaml-language-server: $schema=https://mrdocs.com/docs/mrdocs/develop/_attachments/mrdocs.schema.json

source-root: ../include
multipage: false
generator: adoc

The schema is also attached to this site: mrdocs.schema.json.