Blocks

How to create blocks

Blocks are arguably the most versatile node type in Mau. You can create a block surrounding any amount of document nodes between fences made of four identical characters (with the exception of forward slashes that mark a multi-line comment).

----
This is a block surrounded by `----`.
----

####
This is a block surrounded by `####`.
####

Blocks inside blocks

Blocks can contain any other type of node, including other blocks.

++++
This is the outer block, level 0.

The block has been given border and spacing through a custom template to highlight its boundaries.

####
This is an inner block, level 1.

The block has been given border and spacing through a custom template to highlight its boundaries.

----
This is an inner block, level 2.

The block has been given border and spacing through a custom template to highlight its boundaries.
----
####
++++

Labels and arguments

Blocks support arguments and labels.

[arg1, arg2]
.details Some details
----
This is a block with a label and arguments.
----

Control conditions

Blocks also support control conditions.

:var:44

@if var==42
[arg1, arg2]
.details Some details
----
This block will not be rendered.
----

----
This block will not receive title or arguments.
----

Block engines

Blocks support multiple engines that decide how to process the content. The engine is specified through the argument engine and can have the following values:

• default
• raw
• source

The engine default parses Mau syntax inside the block. Being the default engine type, there is no need to specify it.

[engine=default]
----
This block contains Mau syntax that is processed just like the rest of the document.
----

----
This block behaves in the same way even though it has no arguments.
----

The engine raw

The engine raw preserves the content of the whole block verbatim, but without treating it as source code, just like the macro raw does. The content of the block is inserted into the document as it is.

This means that raw blocks cannot contain other blocks. In case the closing delimiter must be added to the block, the wrapping block should use a different type of fences.

[engine=raw]
----
<p>An HTML paragraph</p>
----

<p>An HTML paragraph</p>

Block isolation

Headers and footnotes included in blocks are not added automatically to the global lists (ToC and the list of footnotes), as blocks are isolated by default. To turn off isolation you can use the argument isolate=false. See more details in Table of contents and Footnotes.