Read Markdown as man pages with lowdown(1) and mandoc(1)

My use case, broadly speaking, is similar to that of many others that maintain a blog. I write my blog in Markdown and often want to check the output to make sure that it’s sane before applying changes.

Formerly, my way of addressing this was to run httpd(8) on localhost and use a shell script I wrote called webtest to render the output. Then, I would preview the changes in my web browser by visiting http://localhost/.

I do still like this method for certain things, such as seeing how CSS is going to look in Firefox. It’s nice to have a completely local, browsable copy of my website.¹ However, for quickly ascertaining whether the output for an article is good or not, this is totally overkill!

This is where lowdown comes in. lowdown has a number of different output modes that can be specified with lowdown -T [mode]. lowdown -T html is typical for blogs.

One day, I got curious and read the man page to look for other output modes and noticed lowdown -T man. Suddenly, it hit me that I could use mandoc(1) to accept, format, and paginate that output like so:

$ lowdown -T man [Markdown file] | mandoc -a

So, it turns out I can RTFM even when proofreading my website. I wrote a small shell function named manmd() to make the process easier and for the novelty of it.

Output can be piped to something other than mandoc if preferred–I use mandoc because it’s included with OpenBSD.

Other options for reading Markdown

It’s worth perusing the respective man pages for interesting options. Looking at mandoc, it’s possible to render lowdown -T man output as a PDF and pipe that into a PDF reader (I like zathura):

$ lowdown -T man [Markdown file] | mandoc -T pdf | zathura -

There is also lowdown -T term, described as “ANSI-escaped UTF-8 output suitable for reading on the terminal.” Here, I paginate the output with less(1), with -R to correctly interpret ANSI color escape sequences.

$ lowdown -T term [Markdown file] | less -R

To disable ANSI color escape sequences (I find the added color doesn’t enhance readability; if anything, it’s very distracting), use --term-no-colour:

$ lowdown -T term --term-no-colour [Markdown file] | less

I also wrote a small shell function for the no color variant of lowdown -T term, readmd(). It’s less janky than manmd(), as entertaining as Markdown converted into man pages can be.