Mau - A template-based markup language
Headers
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
= A very important section
<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
=== A less important section
<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:
= Main section
== Secondary section
== Another secondary section
=== A very specific section
::toc:
You can avoid including a specific header in the TOC using a !
after the last =
= Main section
== Secondary section
===! This header is not in the TOC
::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
= Section 1
== Section 1.1
[tags=notoc]
== Section 1.2
=== Section 1.2.1
== Section 1.3
::toc:exclude_tags=notoc
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.
= A very important section
<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.