Headers

To properly structure some text you need to divide it into sections and the best way to highlight sections is through headers. Mau supports them and automatically stores them in a table of context.

To create a header in Mau use the symbol = followed by the text of the header

= A very important section

Mau converts it into a suitable header in the target format and assigns an ID to it. The level of the header is ruled by the number of = symbols that you use. So, to create a header of level 3 you can write

=== A less important section

Headers and rich text

Headers can contain rich text just like paragraphs. For example you can have styles

== Section _42_

== The function `answer()`

Table of Contents

Mau stores all headers in a Table of Contents that can be created with the command ::toc:

= Main section

Text of the main section

== Secondary section

Text of the secondary section

== Another secondary section

Text of another secondary section

=== A very specific section

Text of the very specific section

---

::toc:

This will be rendered as

You can avoid including specific headers in the TOC using tags. You can tag the headers you don't want to include and pass them to the command ::toc: using the argument exclude_tag. This will also exclude all children of that node.

= Section 1

== Section 1.1

[#notoc]
== Section 1.2

=== Section 1.2.1

== Section 1.3

---

[exclude_tag=notoc]
::toc:

This will exclude from the rendered TOC both Section 1.2 and Section 1.2.1, but not Section 1.3.

Anchors

Headers are automatically assigned an identifier by Mau, which is linked in the Table of Contents.

The identifier is generated by an internal function that takes into account the text and the level of the header to avoid clashes. However, the ID is NOT granted to be unique. The function that generates the identifier can be replaced when using Mau programmatically, providing it in the configuration variable mau.parser.header_anchor_function

The function should accepts text and level, which are the text of the header and the number of equal signs preceding it, and return the ID as a string.

For example you can do something like

def custom_header_anchor(text, level):
    return f"{text[:5]}-{level}"

config = {
    "parser": {
        "header_anchor_function": custom_header_anchor
    }
}

You can read more about configuration variables in Basic syntax and Configuration.

Header macro and IDs

Headers can be linked internally giving them an ID and using the macro header.

To assign an ID to a header simply use arguments

[id=section-42]
= Section 42

Then, at any point of the document you can use the syntax [header](section-42) to generate a link to that header.

The text of the link is automatically set to the text of the header, but if you want you can provide a replacement, e.g. [header](section-42, "the relative section").