Install and Run Mau

Install and Run Mau

This chapter details 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. However, these are not mandatory to run Mau.

Install Mau as a stand-alone tool

Mau is available on PyPI 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

You can get help directly on the command line running

mau --help

The help text lists the available output formats under the option -t. After a fresh installation, Mau provides only the formats core:YamlVisitor and core:JinjaVisitor.

  -t {core:YamlVisitor,core:JinjaVisitor}, --visitor {core:YamlVisitor,core:JinjaVisitor}
                        Output format (default: None)

Install visitors

Mau renders its output through so-called visitors that are available as plugins.

The HTML output plugin source code is available at HTML visitor. You can install it with

pip install mau-html-visitor

The TeX output plugin source code is available at TeX visitor. You can install it with

pip install mau-tex-visitor

After you install plugins, their output format is added to the help output

  -t {mau_html_visitor:HtmlVisitor,core:YamlVisitor,core:JinjaVisitor}, --visitor {mau_html_visitor:HtmlVisitor,core:YamlVisitor,core:JinjaVisitor}
                        Output format (default: None)

As you can notice, Mau provides two visitors out-of-the-box, core:YamlVisitor and core:JinjaVisitor, but those are not useful for an everyday usage. Plugins provide visitors whose name is module:class, where module is the Python module corresponding to the plugin (mau_html_visitor in the example above) and class is the name of the Python class that implements the visitor (HtmlVisitor in the example above).

Run Mau as a stand-alone tool

The simplest command line for Mau is

mau -i INPUT -t FORMAT

that reads the Mau source file INPUT and converts it into the desired FORMAT, saving the output in a file called INPUT.EXT, where EXT is a suitable extension that depends on the chosen format. If the input file has the extension .mau that will be automatically removed.

You can specify the name of the output file using -o

mau -f FORMAT -i INPUT -o OUTPUT

Please note that if you specify the output file no extension will be added automatically.

Example

Make sure you installed the HTML visitor and 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 -t mau_html_visitor:HtmlVisitor -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-aae2">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.

Configuration file

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

mau -c config.yaml -t mau_html_visitor:HtmlVisitor -i test.mau -o test.html

Each value defined in the config file is stored as a variable and can be used in the Mau source. A complete description of the configuration file can be found in Configuration. You can learn more about variables in Mau documents in Basic syntax.

Using Mau programmatically

You can use Mau programmatically in your Python code. See Python interface to know more about the API.

That chapter also details how to use Mau to write posts and pages in Pelican through a specific plugin.