Blocks: built-in types and other features

Over an inner wall he saw the pinnacles of strangely shaped towerlike structures. One of these towers was built in, or projected into the court in which he found himself, and a broad stair led up to it, along the side of the wall.

Robert E. Howard, The Pool of the Black One (1933)

Mau provides some built-in block types that are rendered in a different way.

Quotes¶

The simplest block type that Mau provides is called quote. This block's content is the quote itself, while the secondary content is the source of the quote, commonly called attribution.

[quote]
----
Learn about the Force, Luke.
----
_Star Wars_, 1977

<blockquote>
  <p>Learn about the Force, Luke.</p>
  <cite>
    <p><em>Star Wars</em>, 1977</p>
  </cite>
</blockquote>

Mau 1.x used the key attribution to specify the source of a quote, and that is still available for backward compatibility.

[quote, attribution="Star Wars, 1977"]
----
Learn about the Force, Luke.
----

Please note however that this syntax does not support Mau code in the attribution, so for example you can't use styles.

Admonitions¶

Mau supports admonitions, special blocks that are meant to be rendered with an icon and a title like warnings, tips, or similar things.

The arguments of the block are [admonition, CLASS, ICON, LABEL].

[admonition, source, "fab fa-github", "Source code"]
----
This is my admonition
----

<div class="admonition source">
  <i class="fab fa-github"/>
  <div class="content">
    <div class="title">Source code</div>
    <div>
      <p>This is my admonition</p>
    </div>
  </div>
</div>

Block conditions¶

You can conditionally render a block according to the result of a test. The test is expressed in the form CONDITION:VARIABLE:[VALUE] and is passed to the block through the attribute condition.

:render:yes

[aside, condition="if:render:yes"]
----
This will be rendered
----

[aside, condition="if:render:no"]
----
This will not be rendered
----

You can use boolean values leaving out the VALUE part

:render:

[aside, condition="if:render:"]
----
This will be rendered
----

:!render:

[aside, condition="if:render:"]
----
This will not be rendered
----

You can reverse the condition using ifnot

:render:

[aside, condition="ifnot:render:"]
----
This will not be rendered
----

Block classes¶

You can add custom classes to a block using the attribute classes, which is a comma separated list of names. These classes will be then rendered according to the output format. For example, in HTML these will become CSS classes.

[aside, classes="myclass1,myclass2"]
----
This is a block of type `aside` and a title
----

<div class="aside myclass1 myclass2 ">
  <div class="content">
    <p>This is a block of type <code>aside</code> and a title</p>
  </div>
</div>

Including content¶

As mentioned in the chapter about basic syntax, Mau '#include' directive can be used at any point (at the beginning of the line), and this means that the content of the block can be generated including the content of an external file.

[aside]
----
::#include:/path/to/important_aside.mau
----

This might be very useful for source blocks (see the dedicated chapter)

[source, python]
----
::#include:/path/to/myscript.py
----