“I’ll tell you. I’m going to install a visiplate right over my desk. Right on the wall over there, see!”

Isaac Asimov, I, Robot (1950)

In this chapter I will show you how to install Mau both as a stand-alone tool and as a plugin for Pelican. The only requirements are a working Python3 installation and a virtual environment.

While Python comes preinstalled in several operating systems these days, you can find detailed instructions on how to install it on the Python official website. Virtual environments are covered in the official documentation, but you might want to also explore tools to manage them, like pyenv etc. These are however not mandatory to run Mau.

Install stand-alone Mau

Mau is available on PyPI at https://pypi.org/project/mau/ and to install it you just need to run

pip install mau

At this point you should have the command line tool mau available. You can test it with

mau --version

This book covers Mau v2.x. If you are still using Mau 1.x please consider migrating to the new version. The README file contains the list of incompatibilities between the two versions, which is fortunately short.

Use stand-alone Mau

You can get help directly on the command line running

mau --help

The simplest command line for Mau is

mau -i INPUT.mau

that reads the Mau source file INPUT.mau and converts it into HTML saving the output in a file called accordingly. Mau will strip the extension .mau and replace it with .html.

If you want to specify the output format and the name of the output file you can use the two options -f and -o

mau -f FORMAT -i INPUT -o OUTPUT

where FORMAT is one of the output formats that Mau supports (currently html, asciidoctor, or markua), and both INPUT and OUTPUT are full paths, extensions included.

Example

Create the file test.mau in the current directory with this content

= A test

This is a test for the Mau markup processor.

Now you can run

mau -i test.mau

or

mau -f html -i test.mau -o test.html

That will parse the content of test.mau and render it as HTML into test.html. The content of that file is

<html>
  <head>
  </head>
  <body>
    <h1 id="a-test">A test</h1>
    <p>This is a test for the Mau markup processor.</p>
  </body>
</html>

(minus the formatting which was added here for clarity)

You can now open the output file with your browser

firefox test.html

and enjoy your first document created with Mau.

The configuration file

Mau supports a configuration file written in YAML that can be loaded with the option -c

mau -c config.yml -f html -i test.mau -o test.html

Each value defined in the config file is stored as a variable under the namespace mau, and can be used in the Mau source. See the section about variables to know more about this.

Using Mau in Pelican

You can use Mau to write posts and pages in Pelican. First you need to install the plugin that enables it

pip install pelican-mau-reader

You can see the updated documentation about the plugin on the project page at https://github.com/pelican-plugins/mau-reader but you will find everything you need in this book as well.

The basic usage of the plugin is simple. Every file in your content directory that ends with .mau will be processed by it, and you need to specify metadata using Mau's variables under the namespace pelican. For example

:pelican.title:This is a post written with Mau
:pelican.date:2021-02-17 13:00:00
:pelican.modified:2021-02-17 14:00:00
:pelican.category:tests
:pelican.tags:foo, bar, foobar
:pelican.summary:I have a lot to write

The syntax :name:value is used by Mau to create variables and you can learn more about it in the dedicated chapter.