I’ve been wanting a way to preview Markdown-formatted text files from the terminal, ideally via less. Primarily, I think, because Github encourages it, a lot of open source projects are starting to include a README.md instead of a plain old README¹,²; these marked-down READMEs are easy to view in Github’s web interface but not after (or before) you clone the repo into your own filesystem.

There’s zless that can understand compressed files; why not mdless that can understand Markdown files?

I went looking and stackoverflow came to the rescue with this question and answer about a less-style markdown viewer for UNIX systems, suggesting pandoc as the tool to translate from Markdown format to troff format. The suggested incantation there works for me under Debian Linux but not under Mac OS X because it relies on man’s -l option, which I’m guessing is a GNU addition not supported by BSD man. I had to figure out how to duplicate the processing that man -l does, which I knew involved troff (or groff); it turns out that groff understands a -man flag which predefines the macros used by manpages. The version using groff instead of man -l seems more portable (it works fine under Linux as well as Mac OS X), so that’s what I’ll use.

Hence, the following incantation to view a README.md file:

pandoc -s -f markdown -t man README.md | groff -T utf8 -man | less

Or, a mdless command implemented as a tcsh alias:

alias mdless "pandoc -s -f markdown -t man \!* | groff -T utf8 -man | less"