Markdown For Manuals

Wednesday 4th September, 2013

Things have come a long way when it comes to producing documentation. In the past I’ve spent an huge amount of time grovelling around with Doxygen, and home-made documentation tools. Creating repurposable documentation used to be quite a task. Provided you’re happy to work in markdown, this no longer the case.

For some time I’ve been using markdown in various projects to create HTML and styled text in an editable, but semi-automated fashion. It’s great for getting FileMaker to display styled content without having to get involved with parsing raw HTML. We use it generate this website, via octopress, and it’s become the default method for writing anything that we’re going to keep.

As a predominantly Mac user there’s plenty of support for it. I’m writing this in the excellent Markdown Pro, but the toolbox also includes Marked, Multimarkdown Composer, and the never out of reach nvAlt, (Brett Terpstra’s markdown capable fork of Notaional Velocity.)

One tool that we’ve only just started using though deserves special mention: pandoc. It’s an over-sued cliché to say something is ‘the swiss army knife of X’, but if the Swiss Army had need of a method for converting from markdown, textile, HTML, DocBook, LaTeX, or MediaWiki markup to XHTML, HTML5, Slidy, Slideous, S5, DZSlides, Microsoft Word docx, OpenOffice/LibreOffice ODT, OpenDocument XML, EPUB version 2 or 3, FictionBook2,DocBook, GNU TexInfo, Groff man pages,LaTeX, ConTeXt, LaTeX Beamer,PDF via LaTeX,Markdown, reStructuredText, AsciiDoc, MediaWiki markup, Emacs Org-Mode, or Textile (wait, did I miss any?), well pandoc would be it.

Installation is pretty straightforward, although 2.3Gb download of MacTex for converting to PDF is a chunk, and calling it is a simple as:

pandoc -f markdown mysourcedoc.md -o myfinisheddoc.pdf

Actually, that’s not quite it, as by default it’s formatted for US paper sizes, so actually what we use is:

pandoc -V papersize:“a4paper” -f markdown mysourcedoc.md -o myfinisheddoc.pdf

but you get the idea.

One tiny complaint - at present, in order to get page breaks in (something, for obvious reasons, not covered in the markdown spec) we have to resort to adding

\newpage

before every level 1 or 2 heading. Apparently this is fixable via the templates, but we’ve had little chance to play with it. Being able to move back and forth between formats is very freeing, and we’re investigating moving some legacy documentation from HTML into markdown. All very exciting.