Configuration

Mau supports a YAML configuration file that can be loaded with the -c command line option. Each value in the configuration file is stored in the environment under the mau namespace.

mau -c config.yaml -i input.mau -t mau_html_visitor:HtmlVisitor -o output.html

This chapter documents all configuration variables supported by Mau.

Configuration file structure

The configuration file is a YAML file whose keys are nested under namespaces. For example

config.yaml

parser:
  aliases:
    source:
      args:
        engine: source
      names:
        - language
visitor:
  html:
    pretty: true
  templates:
    paths:
      - templates
    providers:
      - mau-docs-templates
    custom:
      paragraph.html: "<p>{{ content }}</p>"
    prefixes:
      - myprefix

All values in the configuration file are loaded under the mau namespace, so the key visitor.html.pretty becomes mau.visitor.html.pretty in the environment.

Parser configuration

`mau.parser.aliases`

A dictionary of argument aliases. Each alias maps a name to a set of default values that are expanded when the alias is used with the @ prefix in argument lists.

Each alias is a dictionary with three optional keys:

args: a dictionary of named arguments to add.
names: a list of positional names. Unnamed arguments are mapped to these names in order.
subtype: a default subtype for the node.

Mau defines a built-in alias source that expands to engine=source and maps the first positional argument to language. This means [@source, python] is equivalent to [engine=source, language=python].

parser:
  aliases:
    source:
      args:
        engine: source
      names:
        - language

A custom alias can include any combination of these keys. For example

parser:
  aliases:
    note:
      subtype: note
      args:
        engine: default

would allow [@note] to be used in place of [*note, engine=default].

`mau.parser.header_internal_id_function`

A Python function that creates a unique anchor for headers. This can only be set programmatically (not through the YAML configuration). The function prototype is

def header_internal_id(node: HeaderNode) -> str

When not set, the default function creates IDs from the header text (lowercased, sanitised, with spaces replaced by hyphens) followed by a 4-character MD5 hash suffix.

`mau.parser.footnote_unique_id_function`

A Python function that creates a unique ID for footnotes. This can only be set programmatically. The function prototype is

def footnote_unique_id(node: FootnoteNode) -> str

When not set, the default function returns the footnote name unchanged.

`mau.parser.document_wrapper`

The node class used to wrap the entire document content. This can only be set programmatically. The default value is DocumentNode.

`mau.parser.source_highlight_style_aliases`

A dictionary that maps highlight marker characters to their full style names, used in source code blocks. By default, the following aliases are defined

parser:
  source_highlight_style_aliases:
    "+": add
    "-": remove
    "!": important
    "x": error

When a source line ends with a highlight marker like :@+:, the character after @ (in this case +) is looked up in this dictionary and resolved to the style name add.

Visitor configuration

These configuration variables apply to all Jinja-based visitors (HTML, TeX, or any custom visitor).

`mau.visitor.templates.paths`

A list of directory paths where Mau will search for template files. Paths are scanned recursively. Templates found later override earlier ones.

visitor:
  templates:
    paths:
      - templates
      - custom_templates

`mau.visitor.templates.providers`

A list of template provider plugin names to load. Template providers are packages registered under the mau.templates entry point group. They must be explicitly listed here to be loaded.

visitor:
  templates:
    providers:
      - mau-docs-templates

`mau.visitor.templates.custom`

A dictionary of template names and their content, defined inline in the configuration file. Useful for small templates or quick experiments. These templates have the highest priority and override all other sources.

visitor:
  templates:
    custom:
      paragraph.html: "<p>{{ content }}</p>"
      style.style__star.html: "<strong>{{ content }}</strong>"

`mau.visitor.templates.prefixes`

A list of template prefixes to try when resolving template names. When finding a matching template for a node, the visitor first tries templates that include each prefix (via the pf_ component in template filenames), then falls back to templates without a prefix.

visitor:
  templates:
    prefixes:
      - sidebar
      - main

Template loading order

Mau collects templates from several sources always in the same order. If two sources provide two templates with the same name, the one loaded later overrides the other. In the following list, sources are in loading order and thus in increasing order of importance:

Templates from the current visitor.
Templates from template plugins (mau.visitor.templates.providers).
Templates from the local filesystem (mau.visitor.templates.paths).
Templates from the configuration (mau.visitor.templates.custom).

Template context

Every Jinja template receives the node data (see chapter 24) and a variable called config that contains the entire environment as a nested dictionary. This allows templates to access configuration values or user-defined variables.

For example, in a template you can use {{ config.mau.visitor.html.pretty }} to check the current setting, or {{ config.mau.envvars.theme }} to access a variable passed via the command line.

HTML visitor configuration

These configuration variables are specific to the HTML visitor (mau_html_visitor:HtmlVisitor).

`mau.visitor.html.pretty`

A boolean that enables pretty-printed HTML output (with indentation). When enabled, the final HTML output is reformatted using BeautifulSoup for human readability.

visitor:
  html:
    pretty: true

Pretty printing HTML can introduce unwanted spaces inside <code> and <pre> tags. Disable it if you notice formatting issues with inline code or source blocks.

`mau.visitor.html.highlighter`

The name of the syntax highlighter to use for source code blocks. The default value is pygments. This can be overridden per-block by setting a highlighter argument on the block itself.

visitor:
  html:
    highlighter: pygments

`mau.visitor.html.pygments`

A dictionary of options passed to the Pygments HtmlFormatter. Any option accepted by Pygments can be set here. The default is nowrap: true, which tells Pygments not to wrap the output in <div> and <pre> tags.

visitor:
  html:
    pygments:
      nowrap: true
      cssclass: highlight

TeX visitor configuration

The TeX visitor (mau_tex_visitor:TexVisitor) does not define any visitor-specific configuration variables. It uses the shared visitor configuration described above (mau.visitor.templates.*).

Environment files

Additional YAML files can be loaded into the environment using the -e command line option. Each file's content is stored under the namespace mau.envfiles by default.

mau -e data=data.yaml -i input.mau -t mau_html_visitor:HtmlVisitor

The syntax is KEY=PATH where KEY is the namespace key and PATH is the path to the YAML file. If only a path is provided, the filename (without extension) is used as the key.

Values loaded this way are accessible in Mau source as {mau.envfiles.KEY.subkey}.

The namespace can be changed with the --environment-files-namespace option

mau --environment-files-namespace mydata -e data=data.yaml -i input.mau -t mau_html_visitor:HtmlVisitor

In this case, values are accessible as {mau.mydata.data.subkey}.

Environment variables

Variables can be set on the command line using the -v option. Each variable is stored under the namespace mau.envvars by default.

mau -v answer=42 -v name=Arthur -i input.mau -t mau_html_visitor:HtmlVisitor

Values are accessible in Mau source as {mau.envvars.answer}.

The namespace can be changed with the --environment-variables-namespace option

mau --environment-variables-namespace custom -v answer=42 -i input.mau -t mau_html_visitor:HtmlVisitor

In this case, values are accessible as {mau.custom.answer}.