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.


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.


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


Feel free to reach me on Twitter if you have questions. The GitHub issues page is the best place to submit corrections.