Include

Including content

Mau allows you to include content with the syntax << TYPE, where TYPE is the type of content you want to add to your document.

Included content types range from external media like images to generated content like the table of contents, so the output of the inclusion depends strongly on the type of content. The behaviour of the inclusion syntax << TYPE, however, is shared among all types of included content.

In this chapter, we will cover three basic inclusion types: image to include external images, mau to include other Mau files, and raw to include raw content. In the following chapters, we will discuss advanced include options for Mau files, and generate content like the table of contents and the list of footnotes.

How to include an image

You can include an image in a Mau document with the syntax << image:URI, where URI is the location of the image itself. Depending on the target format, the URI can be a local file path (absolute or relative), an HTTP URL, or another type of location.

Mau source code

<< image:"https://placehold.co/600x400/orange/white?text=Hello+World"

• Rendered HTML

Alternative text and classes

You can specify alternative text and classes that are applied to the included image according to the output format and the template.

Mau source code

<< image:"https://unreachab.le/image", alt_text="A beautiful landscape", classes="class1, class2"

• Rendered HTML

How to include Mau text

You can also include files that contain Mau source code and have them parsed and rendered as part of the document. The example will use the file aux/included-text.mau that contains the following code

=== Included content

This is a file with *Mau syntax*.

The file must be reachable by Mau, so the file path must be either absolute or relative to the base path Mau uses when it is executed.

<< mau:aux/included-text.mau

How to include raw content

The macro [raw] allows you to inject a raw piece of text directly into a rendered text node like a paragraph. The syntax << raw:FILENAME is the equivalent at a document level, and injects the content of the file FILENAME directly into the rendered output.

As it happens for the macro [raw], this method of adding content is tied to the output format, so it should be used sparingly if the target is to render the input into several different forms (e.g. a website and a PDF document).

The example will use the file aux/included-raw.html that contains the following code

<p>This is a raw HTML paragraph with a <a href="en.wikipedia.org">link</a></p>

<< raw:aux/included-raw.html

Labels

The include syntax support labels, which might be used for example to create captions for included images.

Mau source code

. A beautiful orange rectangle
<< image:"https://placehold.co/600x400/orange/white?text=Hello+World"

• Rendered HTML

A beautiful orange rectangle

Inline arguments

The include syntax supports inline arguments. The URI must either be the first unnamed argument or be present among the named ones.

Mau source code

<< image:"https://placehold.co/300x100/purple/white"

<< image:uri="https://placehold.co/300x100/blue/white"

• Rendered HTML

Boxed arguments

Arguments for the include syntax can also be passed in the usual boxed fashion, surrounded by square brackets.

You cannot, however, mix inline and boxed arguments.

When you specify boxed arguments you also need to remove the colon after the included media type.

Mau source code

["https://placehold.co/300x100/purple/white"]
<< image

[uri="https://placehold.co/300x100/blue/white"]
<< image

• Rendered HTML

Control conditions

The include syntax also support control conditions.

Mau source code

:var:42

@if var == 42
<< image:"https://placehold.co/600x100/green/white?text=This will be rendered"

@if var == 43
<< image:"https://placehold.co/600x100/red/white?text=This will NOT be rendered"

• Rendered HTML

Include other media types

Mau provides specific code to process the types image and mau, but the syntax allows you to name any type of media. This will be rendered with a specific template, allowing you a great deal of customisation, even though there will be no specific processing in the parser.

The following example is rendered using a custom template for the type placehold that embeds an image created using https://placehold.co just like you saw above. See the chapter about templates for more information about this.

<< placehold: w=600, h=100, bg=48D1CC, text="A custom include!"