Mau: a lightweight markup language

2021-02-22T10:00:00+00:00

What is Mau?¶

Mau is a lightweight markup language heavily inspired by AsciiDoc that makes is very easy to write blog posts or books.

The main goal of Mau is to provide a customisable markup language, reusing the good parts of AsciiDoc and providing a pure Python 3 implementation.

You can find Mau's source code on GitHub.

Why not Markdown or AsciiDoc?¶

Markdown is a very good format, and I used it for all the posts in this blog so far. I grew increasingly unsatisfied, though, because of the lack of some features and the poor amount of customisation that it provides. When I wrote the second version of my book "Clean Architectures in Python" I considered using Markdown (through Pelican), but I couldn't find a good way to create tips and warnings. Recently, Python Markdown added a feature that allows to specify the file name for the source code, but the resulting HTML cannot easily be changed, making it difficult to achieve the graphical output I wanted.

AsciiDoc started as a Python project, but then was abandoned and eventually resurrected by Dan Allen with Asciidoctor. AsciiDoc has a lot of features and I consider it superior to Markdown, but Asciidoctor is a Ruby program, and this made it difficult for me to use it. In addition, the standard output of Asciidoctor is a nice single HTML page but again customising it is a pain. I had to struggle to add my Google Analytics code and a sitemap.xml to the book site.

I simply thought I could try to write my own tool, in a language that I know well (Python). It works, and I learned a lot writing it, so I'm definitely happy. I'd be delighted to know that this can be useful to other people, though.

Pelican¶

A reader for Mau source files is available in Pelican, you can find the code at https://github.com/getpelican/pelican-plugins/pull/1327. Simply add the code to your Pelican plugins directory and activate it adding "mau_reader" to PLUGINS in your file pelicanconf.py. The Mau reader processes only files with the .mau extension, so you can use Markdown/reStructuredText and Mau at the same time.

Development¶

If you are interested you can leave a star on the project on the GitHub page, start using it, or contribute ideas, code, bugfixes.

Feedback¶