Block groups

How to create block groups

Sometimes, you need to treat two or more pieces of text in different ways, but still render them together, possibly with custom templates. A good example would be a textual description and some source code shown side by side, or a text in a language and its translation. In those cases, it is desirable for Mau to be able to access them together.

A block group is a collection of blocks. The group has a name, and each block is assigned a position in the group. The blocks are parsed and made available to the block group template through the include syntax.

To create a block group, assign the group and position arguments to a block

[group=mygroup, position=position1]
----
This is a block in the group `mygroup` at position `position1`.
----

[group=mygroup, position=position2]
----
This is a block in the group `mygroup` at position `position2`.
----

Blocks that belong to a group are not rendered inline. They are stored in an internal manager and made available through the include syntax << blockgroup.

Rendering block groups

To render a block group, use the include syntax << blockgroup followed by a colon and the group name

<< blockgroup:mygroup

This collects all blocks registered under the name mygroup and passes them to a template. The template receives a dictionary of items indexed by their position, so you can access each block individually.

Mixing different block types

The advantage of groups is that you can assign different arguments to each block. For example, you can use different subtypes or even engines

[group=mixedgroup, position=description]
----
This is a normal block with a textual description.
----

[group=mixedgroup, position=code, engine=source, language=python]
----
s = "This is a block with Python content."
----

<< blockgroup:mixedgroup

In this example, the first block is processed with the default engine (Mau syntax), while the second is processed with the source engine (syntax highlighting). Both blocks are collected into the same group and rendered together.

Labels and arguments on block groups

The include << blockgroup supports both boxed and inline arguments, as well as tags and subtypes

[arg1, #tag1, *subtype1, key1=value1]
<< blockgroup:mygroup

<< blockgroup:mygroup, arg1, #tag1, *subtype1, key1=value1