Mau - A template-based markup language
Basic syntax
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
This is Mau source code
If useful, the resulting HTML code will be shown in a block like this
<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
<p>The resulting HTML code</p>
the full output is actually
<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
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
This is a sentence. And another sentence.
and
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
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
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
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
::#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).