Asciidoc & Mutt

I’ve recently started using NeoMutt as my email client. Mutt and NeoMutt are known to be a pain to set up. I highly recommend mutt-wizard, which configures everything you need automatically. Anyway, the thing about NeoMutt is that it is extremely customizable. In fact it is so customizable that you configure how emails are formatted.

I like Asciidoc a lot, so I was looking for an email client that could convert messages written in Asciidoc to HTML before sending them. A was also looking for a way to include mathematical equations inside the body of the messages I write. Well, asciidoctor(1) — the best Asciidoc processor out there — can convert Asciidoc source-files to HTML:

$ asciidoctor -o source.asciidoc output.html

We can can configure NeoMutt to call Asciidoctor for us:

macro compose A "F asciidoctor -o - - \ny^T^Utext/html; charset=utf-8\n" "format a messege with Asciidoctor"

Furthermore, Asciidoctor can format LaTeX and AsciiMath equations using MathJax. Case closed then? Unfortunately there are three problems with this “default” approach:

1. The HTML code generated by Asciidoctor by default includes a bunch of crap that we don’t need. It includes various style-sheets, FontAwesome icons, fonts and some other bloat. I personally don’t want any of that, I just want a crappy looking, raw HTML file strait from the 90s.
2. The HTML layout of pages generated by Asciidoctor is extremely bad by default. Besides disregarding basic ARIA guidelines entirely, Asciidoctor (by default) commits several HTML-sins, such as using the <i> tag for icons.
3. As previously stated, Asciidoctor uses MathJax for formatting mathematical equations, which is a JavaScript library. Most email-clients block JavaScript execution entirely (for obvious reasons), which mostly likely means equations in our messages wouldn’t be formatted at all.

You may have noticed I used the phrase “by default” a lot in the previous paragraphs. That is because Asciidoctor is somewhat customizable too: by providing our own Haml / Slim templates we can customize how the source code is converted to HTML. Furthermore, Haml templates allows us to run arbitrary Ruby code, which means we can leverage libraries like mathematical and asciimath to convert LaTeX/AsciiMath code to SVG source code — which allow us to render equations as HTML in a format most email clients will be able to read.

I’ve written my own Haml templates to convert Asciidoctor to plain HTML that can be read by most email clients. You can check them out in here: gitlab.com/pablo-escobar/dotfiles/-/tree/master/.config/mutt/asciidoc-template. Feel free to download them and change them however you want. I’ve disabled some Asciidoc features, such as videos and audio — I figured most email clients wouldn’t be able to process those — but most of the functionality is still there.

We can can configure NeoMutt to call Asciidoctor for us — and provide some decent output:

macro compose A "F asciidoctor -T path/to/the/template/files -o - - \ny^T^Utext/html; charset=utf-8\n" "format a messege with Asciidoctor"

Checkout asciidoctor-backends for more details on how to write Asciidoc Haml/Slim templates — those are the (hideous) default templates, but they are a good starting-point.