The abbot gave him a brief glare and began reading. The silence was awkward. “You found this over in the ‘Unclassified’ section, I believe?” he asked after a few seconds.

Walter M. Miller Jr., A Canticle for Leibowitz (1959)

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

Mau source
= A very important section
HTML output
<h1 id="a-very-important-section">A very important section</h1>

A very important section

As you can see Mau converts it into a tag h1 and automatically 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

Mau source
=== A less important section
HTML output
<h3 id="a-less-important-section">A less important section</h3>

A less important section

Headers and TOC

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

Mau source
= Main section

== Secondary section

== Another secondary section

=== A very specific section

::toc:

Main section

Secondary section

Another secondary section

A very specific section

You can avoid including a specific header in the TOC using a ! after the last =

Mau source
= Main section

== Secondary section

===! This header is not in the TOC

::toc:

Main section

Secondary section

This header is not in the TOC

Pay attention that this removes the header from the TOC but doesn't remove the child headers, which will be attached to the previous header. A better way to selectively remove headers and their children from the TOC is to tag them and exclude them

Mau source
= Section 1

== Section 1.1

[tags=notoc]
== Section 1.2

=== Section 1.2.1

== Section 1.3

::toc:exclude_tags=notoc

Section 1

Section 1.1

Section 1.2

Section 1.2.1

Section 1.3

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

Please note that you can pass multiple comma-separated tags to exclude_tags, e.g. ::toc:exclude_tags="tag1,tag2".

Anchors

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

Mau source
= A very important section
HTML output
<h1 id="a-very-important-section">A very important section</h1>

The identifier is NOT granted to be unique, as two headers with the same text would also have identical identifiers. The function that generates the identifier can be replaced when using Mau programmatically, providing it in the variable mau.header_anchor_function. See the sections about variables and about using Mau in your code for more information.