List of nodes

The financial records were fairly simple — the purchase of this or that trivial toy or bit of trumpery jewelry; lists of presents given and received; a somewhat more meticulous listing of jewels of genuine value, inheritances, or gifts.

Lois McMaster Bujold, The Curse of Chalion (2001)

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 paragraph or in a document. It can be nested if this node is created automatically as part of another node.
  • See also: a list of related nodes.
  • Syntax: a description of the syntax used to create the node.
  • Templates: the templates for this node. See Basic templates to learn about templates.
  • 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 that can be used directly in Jinja conditional statements.
  • 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 insert some HTML.
  • VALUE1 | VALUE2 | VALUE3: the value can only be one of the listed ones.
  • SPECIAL: usually a more complex Python datatype like a list of tuples. See the description of the node for more details.

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

  • parent: NODE = None The parent node.
  • parent_position: primary | secondary = None The position of the node in the parent.
  • children: list[NODE] = [] The list of children nodes.
  • subtype: str = None The subtype of the node.
  • args: list[str] = [] The unnamed arguments.
  • kwargs: dict[str] = {} The named arguments.
  • tags: list[str] = [] The tags.

Every document node also supports title, attributes, and controls, which are not going to be mentioned unless necessary.

To simplify the use of this chapter, nodes are listed in alphabetical order instead of being grouped per topic like in the rest of the book.

Not all nodes in this list can be directly created in Mau documents. Some, like callouts or ToC entries, are created automatically as part of other nodes. However, such nodes will be present in the AST, and thus can be styled using templates.

Block

Description:

This node represents a generic block. Blocks can isolate text and process it in several different ways depending on the engine. Blocks capture the text between fences into primary_content and the paragraph immediately after the closing fence (adjacent to it) into secondary_content.

Documentation: Blocks

Scope: document

See also: Source (block), Block group

Syntax:

Mau source
----
Content
----

Fences are made of any 4 identical characters but four slashes ////.

Templates:

  • block.{engine}
  • block

Fields

  • classes: list[str] = [] A list of classes assigned to this block.
  • engine: str = None The engine that Mau used to process the block.
  • preprocessor: str = None The preprocessor that Mau used for this block.
  • content: TARGET: the primary content (Mau text between fences).
  • secondary_content: TARGET: the secondary content (Mau text just below the closing fence.

Block group

Description:

A set of blocks belonging to the same group, each of them with a position.

Documentation: Block groups

See also: Block

Scope: document

Syntax:

Mau source
::blockgroup:GROUP_NAME

Templates

  • block_group.{group_name}
  • block_group

Fields

  • group_name: str: the name of the group.
  • group: dict:
    • position: TARGET: the key position is the name of an assigned position and the value is the block corresponding to it.

Callout

Description:

This node represents a callout attached to a line of code in a source code block.

This node cannot be created in isolation, it is generated automatically when parsing source code blocks.

Documentation: Source code blocks

Scope: nested

See also: Source (block)

Templates

  • callout

Fields

  • marker: str The label of this callout.

Callout entry

Description:

This node represents an entry in the list of callouts. This list is usually presented at the end of a source block to show the text associated with each callout.

This node cannot be created in isolation, it is generated automatically by source blocks.

Documentation: Source code blocks

See also: Source (block)

Scope: nested

Templates

  • callouts_entry

Fields

  • marker: str The label of this callout.
  • value: str The text associated with this callout.

Caret (style)

Description:

This node represents the text between two carets.

Documentation: Formatting text

See also: Star (style), Tilde (style), Underscore (style)

Scope: paragraph

Syntax ^TEXT^

Templates

  • style.caret
  • style

Fields

  • value: str = caret The style type.
  • content: TARGET The content of the node.

Class (macro)

Description:

This node represents one of more classes to a piece of text.

Documentation: Formatting text

Scope: paragraph

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

Templates

  • macro.class
  • macro

Fields

  • classes: list(str) The list of classes.
  • content: TARGET The content of the node.

Container

Description:

This node is used to wrap the whole document. The variable mau.parser.content_wrapper is used to control which node to use for such purpose and its default value is an instance of this node.

See also: Document

Scope: document

Templates

  • container

Fields

  • content: TARGET The content of the container.

Content

Description:

This node represents generic content imported into the document, and has a specific implementation only for the type image. It can be used to achieve custom effects without involving blocks, whose syntax is more invasive.

See also: Image (content)

Scope:document

Syntax:

Mau source
<< TYPE:URI

Templates

  • content-{content_type}
  • content

Fields

  • content_type: str The type of this content.
  • title: TARGET An optional title for the content.

Document

Description:

This node is used to wrap the whole document. The variable mau.parser.content_wrapper is used to control which node to use for such purpose.

See also: Container

Scope: document

Templates

  • document

Fields

  • content: TARGET The content of the document.

Footnote (macro)

Description:

This node represents the reference to a footnote.

Documentation: Footnotes

See also: Footnotes (command), Footnotes entry

Scope: paragraph

Syntax: [footnote](NAME)

Templates

  • macro.footnote
  • macro

Fields

  • content: TARGET The content of the footnote defined by the companion block.
  • number: str The number of this footnote.
  • reference_anchor: str The anchor to the reference (this node).
  • content_anchor: str The anchor to the content (the footnotes entry).

Footnotes (command)

Description:

This node represents the list of footnote definitions.

Documentation: Footnotes

See also: Footnote (macro), Footnotes entry

Scope: document

Syntax:

::footnotes:

Templates

  • footnotes

Fields

  • entries: list(TARGET) This is the list of footnotes, each being the rendering of a footnote entry.

Footnotes entry

Description:

This node represents an entry in the list of footnotes definitions. it is created automatically for each footnote defined in the text.

Documentation: Footnotes

See also: Footnote (macro), Footnotes (command)

Templates

  • footnotes_entry

Fields

  • content: TARGET The content of the footnote defined by the companion block.
  • number: str The number of this footnote.
  • reference_anchor: str The anchor to the reference (the macro).
  • content_anchor: str The anchor to the content (this node).

Header

Description:

This node represents a header. It can be given an id through arguments that is then linked using a macro header.

Headers are given an anchor created using a default function. The function can be replaced using the variable mau.parser.header_anchor_function, and the individual anchor of a header can be overwritten through arguments with the keyword anchor.

Documentation: Headers

See also: ToC (command), ToC entry, Header (macro)

Scope: document

Syntax:

Mau source
[OPTIONAL ARGUMENTS]
= Header

Templates

  • header

Fields

  • value: TARGET The text of the header.
  • level: int The level of the header, 1 being the highest.
  • anchor: str The anchor of the header if the template wants to set up cross-references between it and the ToC.

Header (macro)

Description:

This node represents a link to a header in the same document.

Documentation: Headers

See also: ToC (command), ToC entry, Header

Scope: paragraph

Syntax: [header](ID, TEXT)

Templates

  • macro.header

Fields

  • header: dict
    • anchor: str The anchor of the connected header.
    • value: TARGET The text of the header.
    • level: int The level of the header, 1 being the highest.
  • content: TARGET The text of the link if specified, otherwise the text of the header.

Horizontal rule

Description:

This node inserts a horizontal rule.

Documentation: Formatting text

Scope: document

Syntax:

Mau source
---

Templates

  • horizontal_rule

Image (content)

Description:

This node represents an image included in the document.

Documentation: Images

See also: Content, Image (macro)

Scope: document

Syntax:

Mau source
<< image:URI

Templates

  • content_image

Fields

  • uri: str The URI of the image file.
  • alt_text: str Alternative text to show if the image cannot be loaded.
  • classes: list[str] List of classes to append to the target node.
  • title: str Title (caption) of the image.

Image (macro)

Description:

This node represents an image in a paragraph.

Documentation: Images

See also: Image (content)

Scope: paragraph

Syntax: [image](URI, ALT_TEXT, WIDTH, HEIGHT)

Templates

  • macro.image

Fields

  • uri: str The URI of the image in a format understood by the target processor.
  • alt_text: str The alternative text used if the image cannot be loaded.
  • width: str The width of the image.
  • height: str The height of the image.

List

Description:

This node represents a list of items. The list can be ordered or unordered, and items can be nested. Each item in the template is either a single item (rendered with the relative template) or a sublist (rendered with the same template as the whole list).

This node is created automatically when a list item is found in the document. The node is also used for nested list items.

Documentation: Lists

See also: List item

Templates

  • list

Fields

  • ordered: bool Whether the list is ordered or not.
  • items: TARGET The list items.
  • main_node: bool Whether this is the main list of a sublist.

List item

Description:

This node represents a single item in a list. This node is created

Documentation: Lists

See also: List

Scope: document

Syntax:

Mau source
* Unordered node level 1
** Unordered node level 2
...
# Ordered node level 1
## Ordered node level 2

A list item is always contained in a list node.

Templates

  • list_item

Fields

  • level: int The level of nesting (1 is the first level).
  • content: TARGET The content of this item (which might be a sublist).

Description:

This node represents a hypermedia link to a URL.

Documentation: Formatting text

See also: Mailto (macro)

Scope: paragraph

Syntax: [link](TARGET, TEXT)

Templates

  • macro.link

Fields

  • target: str The target URL.
  • text: TARGET The text of the link.

Mailto (macro)

Description:

This node represents an email link. The macro is a wrapper around Link (macro), but the output URI is prefixed by mailto:.

Documentation: Formatting text

See also: Link (macro)

Paragraph

Description:

This node represents a paragraph of text.

Documentation: Basic syntax

Scope: document

Syntax:

Mau source
Any line of text that doesn't match another page node.

Templates

  • paragraph

Fields

  • content: TARGET: the content of the paragraph

Raw

Description:

This node represents raw text. This is generated automatically for each line in a block that uses the engine raw.

Documentation: Block engines and custom definitions

Scope: document

Syntax:

Mau source
Content that has to be included verbatim in the document.

Templates

  • raw

Fields

  • content: TARGET: the content of the paragraph

Sentence

Description:

This node represents a sentence, which is a wrapper for the text contained in nodes like titles and headers. It behaves like a paragraph but it's not a document node.

Templates

  • sentence

Fields

  • content: TARGET: the content of the sentence

Source (block)

Description:

This node represents included source code.

Callouts are saved in two lists, markers and callouts.

  • markers is a list of tuples (linenum, text), where linenum is the number of a line, and text is the label assigned to that callout.
  • callouts is a list of callout entries.

Code is provided as a list of tuples (line, callout). The variable line contains the line of code in the target format (possibly highlighted) and callout is either the rendered form of a callout (using the relative template) or None.

Documentation: Source code blocks

See: Block, Callout, Callout entry

Scope: document

Syntax

Mau source
[*source, LANGUAGE]
----
CONTENT
----

Templates

  • source.{language}
  • source

Fields

  • language: str The language of the code contained in this block
  • callouts: list[TARGET] A list of callout entries
  • markers: list[SPECIAL] List of markers (see description)
  • highlights: list[int] List of lines that have to be highlighted
  • delimiter: str Callouts delimiter
  • code: SPECIAL Code and callouts (see description)
  • title: str Title of this block
  • classes: list[str] A list of classes assigned to this block
  • preprocessor: str The preprocessor (currently not in use)

Star (style)

Description:

This node represents the text between two stars.

Documentation: Formatting text

See also: Caret (style), Tilde (style), Underscore (style)

Scope: paragraph

Syntax ^TEXT^

Templates

  • style.star
  • style

Fields

  • value: str = star The style type.
  • content: TARGET The content of the node.

Text

Description:

This node represents standard text.

Documentation: Formatting text

Scope: paragraph

Templates

  • text

Fields

  • value: str The text

Tilde (style)

Description:

This node represents the text between two tildes.

Documentation: Formatting text

See also: Caret (style), Star (style), Underscore (style)

Scope: paragraph

Syntax ^TEXT^

Templates

  • style.tilde
  • style

Fields

  • value: str = tilde The style type.
  • content: TARGET The content of the node.

ToC (command)

Description:

This node represents the list of all headers (Table of Contents).

Documentation: Headers

See also: Header, ToC entry, Header (macro)

Scope: document

Syntax:

Mau source
::toc:

Templates

  • toc

Fields

  • entries: list[TARGET] This is the list of headers, each being the rendering of a ToC entry.

ToC entry

Description:

This node represents an entry in the Table of Contents.

Documentation: Headers

See also: Header, ToC (command), Header (macro)

Templates

  • toc_entry

Fields

  • value: str The header contained in this node
  • anchor: str The anchor of the header
  • children: TARGET The rendered list of children (rendered as the whole ToC)

Underscore (style)

Description:

This node represents the text between two underscores.

Documentation: Formatting text

See also: Caret (style), Star (style), Tilde (style)

Scope: paragraph

Syntax ^TEXT^

Templates

  • style.underscore
  • style

Fields

  • value: str = underscore The style type.
  • content: TARGET The content of the node.

Verbatim

Description:

This node represents verbatim text, and is useful to render code inside paragraphs.

Documentation: Formatting text

Scope: paragraph

Syntax: `TEXT`

Templates

  • verbatim

Fields

  • value: str The verbatim text