List of nodes

This chapter contains the full documentation of all nodes generated by Mau. For each one of them you will find:

Description: a simple description of the node.
Scope: whether the node can be found in a document or in a paragraph. It can be nested if this node is created automatically as part of another node.
Supports: features available for this node. Can include labels, control flow (@if), and argument types (boxed or inline). Only listed for document-scope nodes.
Syntax: a description of the syntax used to create the node.
Templates: the base template name for this node (see chapter 23 for template naming and selection).
Custom template fields: fields exposed via custom_template_fields that enable specialised template names. Only listed for nodes that have them.
Fields: the variables passed to the Jinja template.

Fields have a name, a type, and a description. Type is one of

bool: a Python boolean.
int: a Python integer.
list[type]: a list of values of the given type.
dict: a dictionary.
str: a Python string that contains pure text.
TARGET: text in the target format. For example when rendering in HTML a field of type TARGET will contain HTML.
NODE: a nested node, rendered by its own template.

Every node receives the following fields, which won't be repeated for each one of them

_type: str The node type.
args: list[str] The positional arguments.
kwargs: dict The keyword arguments.
tags: list[str] The tags.
internal_tags: list[str] The internal tags.
subtype: str The subtype of the node.

To simplify the use of this chapter, nodes are listed in alphabetical order.

Block

Description: This node represents a generic block. Blocks can isolate text and process it in several different ways depending on the engine.

Scope: document

Supports: labels, control, boxed arguments

Syntax:

[ARGUMENTS]
----
Content
----

Fences are made of any 4 identical characters except //// (which denotes a multi-line comment).

Templates: block

Fields:

classes: list[str] A list of classes assigned to this block.
content: TARGET The rendered content of the block.
labels: dict Dictionary of labels attached to this block.

Block group

Description: A set of blocks belonging to the same group, each with a position. This node accepts boxed or inline arguments (but not both simultaneously).

Scope: document

Supports: labels, control, boxed and inline arguments

Syntax:

With inline arguments:

<< blockgroup:GROUP_NAME

or with boxed arguments:

[group=GROUP_NAME]
<< blockgroup

Templates: blockgroup

Custom template fields: name (the group name). For example, the template blockgroup.name__example.html matches a block group named example.

Fields:

name: str The name of the group.
items: dict A dictionary where each key is a position name and the value is the rendered block group item at that position.
labels: dict Dictionary of labels.

Block group item

Description: This node represents a single block within a block group. It is created automatically when blocks with group and position arguments are collected into a group.

Scope: nested

Templates: blockgroup-item

Custom template fields: position (the position name). For example, the template blockgroup-item.position__code.html matches an item at position code.

Fields:

position: str The position name within the group.
block: dict The nested block data (including classes, content, labels).

Condition

Description: This node represents a conditional logic statement. It is created automatically when control conditions are parsed.

Scope: nested

Fields:

variable: str The variable being tested.
comparison: str The comparison operator (==, !=).
value: str The value being compared against.

Document

Description: The root node that wraps the entire document.

Scope: document

Templates: document

Fields:

content: TARGET The rendered content of the document.

Footnote

Description: This node represents a footnote definition, created by a block with the footnote argument.

Scope: nested

Syntax:

[footnote=NAME]
----
Footnote content.
----

Templates: footnote

Fields:

name: str The unique name of the footnote.
public_id: str The public-facing identifier (typically a number).
internal_id: str The internal unique identifier.
content: TARGET The rendered content of the footnote.

Footnotes

Description: This node represents the list of all footnote definitions in the document. This node accepts boxed or inline arguments (but not both simultaneously).

Scope: document

Supports: labels, control, boxed and inline arguments

Syntax:

<< footnotes

or with boxed arguments:

[*mysubtype]
<< footnotes

Templates: footnotes

Fields:

footnotes: list[NODE] The list of footnotes items.
labels: dict Dictionary of labels.

Footnotes item

Description: This node represents a single entry in the footnotes list. It is created automatically for each footnote.

Scope: nested

Templates: footnotes-item

Fields:

footnote: dict The nested footnote data (including name, public_id, internal_id, content).

Header

Description: This node represents a header. Headers are given an automatic internal ID that can be used for cross-references. The ID can be overridden with the name argument.

Scope: document

Supports: labels, control, boxed arguments

Syntax:

= Header level 1
== Header level 2
=== Header level 3

With boxed arguments:

[name=my-header]
= Header level 1

Templates: header

Fields:

level: int The level of the header (1 being the highest).
internal_id: str The unique anchor ID.
name: str The custom name if provided via [name=...].
content: TARGET The rendered text of the header.
labels: dict Dictionary of labels.

Horizontal rule

Description: This node inserts a horizontal rule.

Scope: document

Supports: labels, control, boxed arguments

Syntax:

---

With boxed arguments:

[*special]
---

Templates: horizontal-rule

Fields:

labels: dict Dictionary of labels.

Include

Description: This node represents generic included content. This node accepts boxed or inline arguments (but not both simultaneously).

Scope: document

Supports: labels, control, boxed and inline arguments

Syntax:

With inline arguments:

<< type:uri

or with boxed arguments:

[uri]
<< type

Templates: include

Custom template fields: ctype (the content type). For example, the template include.ctype__csv.html matches an include with content type csv.

Fields:

ctype: str The type of the included content.
labels: dict Dictionary of labels.

Include image

Description: This node represents an image included in the document as a stand-alone element. This node accepts boxed or inline arguments (but not both simultaneously).

Scope: document

Supports: labels, control, boxed and inline arguments

Syntax:

With inline arguments:

<< image:path/to/image.png

or with boxed arguments:

[uri=path/to/image.png, alt_text="My alt text"]
<< image

Templates: include-image

Fields:

uri: str The URI of the image file.
alt_text: str Alternative text.
classes: list[str] List of CSS classes.
labels: dict Dictionary of labels.

Include Mau

Description: This node represents an included Mau file. The file is parsed and its content is merged into the document. This node accepts boxed or inline arguments (but not both simultaneously).

Scope: document

Supports: labels, control, boxed and inline arguments

Syntax:

With inline arguments:

<< mau:path/to/file.mau

or with boxed arguments:

[uri=path/to/file.mau]
<< mau

Templates: include-mau

Fields:

uri: str The path to the included file.
content: TARGET The rendered content of the included file.
labels: dict Dictionary of labels.

Include raw

Description: This node represents an included file whose content is treated as raw text. This node accepts boxed or inline arguments (but not both simultaneously).

Scope: document

Supports: labels, control, boxed and inline arguments

Syntax:

With inline arguments:

<< raw:path/to/file.txt

or with boxed arguments:

[uri=path/to/file.txt]
<< raw

Templates: include-raw

Fields:

uri: str The path to the included file.
content: TARGET The raw content.
labels: dict Dictionary of labels.

Label

Description: This node represents a label attached to a document node. Labels provide metadata such as titles or citations.

Scope: nested

Syntax:

.role Content

placed before the node it labels.

Templates: label

Custom template fields: role (the label role). For example, the template label.role__title.html matches a label with role title.

Fields:

role: str The label role (e.g. title, cite).
content: TARGET The rendered content of the label.

List

Description: This node represents a list of items. The list can be ordered or unordered.

Scope: document

Supports: labels, control, boxed arguments

Syntax:

* Unordered item
* Unordered item

# Ordered item
# Ordered item

With boxed arguments:

[*warning, start=3]
# Ordered item
# Ordered item

Templates: list

Fields:

ordered: bool Whether the list is ordered.
main_node: bool Whether this is the main list (not a nested sublist).
start: int The starting number for ordered lists.
content: TARGET The rendered list items.
labels: dict Dictionary of labels.

List item

Description: This node represents a single item in a list.

Scope: nested

Templates: list-item

Fields:

level: int The nesting level (1 is the first level).
content: TARGET The rendered content of this item.

Macro

Description: This node represents a generic custom macro. It is created when a macro name does not match any built-in macro.

Scope: paragraph

Syntax: [name](args)

Templates: macro

Custom template fields: name (the macro name). For example, the template macro.name__badge.html matches a custom macro called badge.

Fields:

name: str The macro name.

Macro class

Description: This node applies one or more CSS classes to a piece of text.

Scope: paragraph

Syntax: [class]("text", class1, class2)

Templates: macro-class

Fields:

classes: list[str] The list of classes.
content: TARGET The rendered content.

Macro footnote

Description: This node represents a reference to a footnote within text.

Scope: paragraph

Syntax: [footnote](NAME)

Templates: macro-footnote

Fields:

footnote: dict The nested footnote data (including name, public_id, internal_id, content).

Macro header

Description: This node represents an internal link to a header in the document.

Scope: paragraph

Syntax: [header](NAME, "text")

Templates: macro-header

Fields:

target_name: str The name of the target header.
header: dict The nested header data (including level, internal_id, content).
content: TARGET The link text (defaults to the header text if not specified).

Macro image

Description: This node represents an inline image within text.

Scope: paragraph

Syntax: [image]("uri", alt_text, width, height)

Templates: macro-image

Fields:

uri: str The URI of the image.
alt_text: str Alternative text.
width: str The width of the image.
height: str The height of the image.

Macro link

Description: This node represents a hyperlink. The [mailto] macro also creates this node, automatically prefixing the target with mailto:.

Scope: paragraph

Syntax: [link](TARGET, "text") or [mailto](EMAIL, "text")

Templates: macro-link

Fields:

target: str The target URL (or mailto: address for email links).
content: TARGET The rendered link text.

Macro raw

Description: This node represents raw inline content that is not processed by Mau.

Scope: paragraph

Syntax: [raw]("content")

Templates: macro-raw

Fields:

value: str The raw content.

Macro unicode

Description: This node represents a Unicode code point.

Scope: paragraph

Syntax: [unicode](CODE_POINT)

Templates: macro-unicode

Fields:

value: str The Unicode code point (e.g., 1F30B).

Paragraph

Description: This node represents a paragraph of text made of one or more lines.

Scope: document

Supports: labels, control, boxed arguments

Syntax: Any line of text that doesn't match another document node.

With boxed arguments:

[*warning]
This is a warning paragraph.

Templates: paragraph

Fields:

content: TARGET The rendered paragraph lines.
labels: dict Dictionary of labels.

Paragraph line

Description: This node represents a single line within a paragraph.

Scope: nested

Templates: paragraph-line

Fields:

content: TARGET The rendered inline content of the line.
labels: dict Dictionary of labels.

Raw

Description: This node represents a block of raw (unprocessed) text, generated by blocks with engine=raw.

Scope: document

Supports: labels, control, boxed arguments

Syntax:

[engine=raw]
----
Content that is included verbatim.
----

Templates: raw

Fields:

classes: list[str] A list of classes assigned to this block.
content: TARGET The raw content.
labels: dict Dictionary of labels.

Raw line

Description: This node represents a single line of raw content. It is created automatically inside raw blocks.

Scope: nested

Templates: raw-line

Fields:

value: str The raw line of text.

Source

Description: This node represents a source code block, generated by blocks with engine=source.

Scope: document

Supports: labels, control, boxed arguments

Syntax:

[engine=source, language=python]
----
def hello():
    pass
----

or with the alias

[@source, python]
----
def hello():
    pass
----

Templates: source

Fields:

language: str The programming language.
classes: list[str] A list of classes assigned to this block.
content: list[NODE] The list of source line nodes.
labels: dict Dictionary of labels.

Source line

Description: This node represents a single line of source code. It is created automatically inside source blocks.

Scope: nested

Templates: source-line

Fields:

line_number: str The line number.
line_content: str The line of source code.
highlight_style: str The highlight style (if any, e.g. added, removed).
marker: NODE The source marker node (if any).

Source marker

Description: This node represents a marker annotation attached to a source code line.

Scope: nested

Templates: source-marker

Fields:

value: str The marker label.

Style

Description: This node represents styled text. The style field determines the type of styling applied.

Scope: paragraph

Syntax:

*text* - style star
_text_ - style underscore
^text^ - style caret
~text~ - style tilde

Templates: style

Custom template fields: style (the style type). For example, the template style.style__star.html matches *bold* text.

Fields:

style: str The style type (star, underscore, caret, tilde).
content: TARGET The rendered styled content.

Text

Description: This node represents plain text.

Scope: paragraph

Templates: text

Fields:

value: str The text content.

ToC item

Description: This node represents a single entry in the Table of Contents. It is created automatically.

Scope: nested

Templates: toc-item

Fields:

header: dict The nested header data (including level, internal_id, content).
entries: list[NODE] Nested ToC items (children of this header).

Verbatim

Description: This node represents verbatim (inline code) text.

Scope: paragraph

Syntax: `text`

Templates: verbatim

Fields:

value: str The verbatim text.