Some of the newer ones are having trouble because they never really mastered some basic techniques, but they’re working hard and improving.

Orson Scott Card, Ender's Game (1985)

This and the following chapters will give you an overview of the basic syntax for paragraphs, styles, and inline elements like links and images. If you are familiar with either Markdown or Asciidoctor none of these will be a surprise to you, but I will describe everything assuming the reader doesn't know any markup language.

I will assume you followed the instructions in the previous chapter and know how to run Mau in a stand-alone fashion, or that you are running it in Pelican. Either way, I will refer to generic input and output, meaning respectively the Mau source and the HTML final result. I will show the source code in a block like this

Mau source
This is Mau source code

If useful, the resulting HTML code will be shown in a block like this

HTML output
<p>The resulting HTML code</p>

The rendered version of the resulting HTML will be shown with an aside like

This is the rendered output

Please keep in mind that the resulting HTML I will show is rendered using this website's CSS, so some of the styles might differ when you open your output file with your browser.

Please also note that I will skip the HTML boilerplate to keep examples compact and readable. When you see a block with the resulting HTML like

HTML output
<p>The resulting HTML code</p>

the full output is actually

HTML output
<html>
  <head>
  </head>
  <body>
    <p>The resulting HTML code</p>
  </body>
</html>

Finally, remember that both Markdown and Asciidoctor have a fixed rendering, while the output in Mau is ruled by templates. What you see in the output HTML and in the rendered boxes is the result of Mau's default templates, but those can be overrided at any time, as we will see in a later chapter.

Paragraphs

Mau converts an input text file into something more complicated, usually written using HTML. Mau performs this in a line-by-line fashion, so you should always assume that a newline terminates the current element.

The simplest element in Mau is a line of text that forms a paragraph

Mau source
This is a line of text.

This is a line of text.


Adjacent lines of text are automatically joined into a single paragraph, so both

Mau source
This is a sentence. And another sentence.

and

Mau source
This is a sentence.
And another sentence.

will be rendered as

This is a sentence. And another sentence.


To separate paragraphs you need to insert one or more empty lines. For example

Mau source
This is a sentence.

And another sentence.

This is a sentence.

And another sentence.

Comments

Mau supports both single-line and multi-line comments. A single line comment uses double slashes

Mau source
This is a sentence.

And another sentence.

// This is a comment and won't be rendered

This is a sentence.

And another sentence.


Multi-line comments are surrounded by four slashes on a separate line

Mau source
This is a sentence.

And another sentence.

////
This is also a comment
but it's spread on
multiple lines
for fun and to be a
little more readable
////

This is a sentence.

And another sentence.

Arguments

As we will see later, some advanced commands in Mau accept arguments, which are not too different from standard function arguments in programming languages. The most important thing to remember is that Mau values are always strings, so arguments do not really have types.

Arguments can appear between round brackets (), square brackets [], or directly after a command, depending on the context. This will be clearly specified in each section when arguments are discussed.

Arguments can be unnamed or named. An unnamed argument has just a value, for example html, while a named one has a key and a value linked by an equal sign, like language=html. There can't be a space between the key and the value, so an argument like language = html is invalid.


Multiple arguments are separated by commas, optionally followed by one or more spaces. So, source,html and source, html are both valid, and the same is valid for named arguments, as source,language=html and source, language=html are equally accepted by the parser.

In the documentation, arguments will be given uppercase (e.g. TYPE), and named ones will followed by an equal sign (e.g. LANGUAGE=). You can avoid specifying the key if you pass argument values respecting the order provided in the documentation. So, if in a certain context you have to provide TYPE, LANGUAGE= you can either give source, html or source, language=html. Unnamed arguments can never follow named ones.


If an argument contains one or more spaces or commas you need to surround it with quotes, e.g. attribution="J.R.R. Tolkien" or classes="class1,class2".

If the arguments are surrounded by braces you should use quotes also whenever the value contains the closing bracket. E.g. (attribution="The (real) author"). Here, the ) after real would be considered the closing bracket if not surrounded by quotes.

If you need to pass quotes as value of an argument you need to escape them, e.g. attribution="The so-called \"author\"".

Macros

Mau allows you to run functions called "macros". Macros always come in the form [NAME](ARGUMENTS) where NAME is the name of the macro and ARGUMENTS is a string formatted as described in the previous section. Built-in macros will be described in the following chapters.

Include other files

Mau has an initial support for including other files through the directive #include. Directives are special commands that are processed before the Mau code is properly parsed

Mau source
::#include:/path/to/file.mau

Since the inclusion happens during the very first stages of the processing, you can also include files inside blocks (see the dedicated chapter).