Documentation is not hard though there is a temptation to make it so. In this post, we’ll go over the details of generating documentation that can be exported to a beautifully typeset PDF and HTML from one source file. In case you're interested, here are the results: Markdown, PDF, XHTML. Because we'll want to produce the final documents in multiple formats, whatever we write will have to be formated in a simple “meta” syntax that can eventually be converted. For a brief moment along my personal documentation journey, I was led astray by xml, docbook, toolchains, and a dizzying myriad of other meta format options.
Salvation By MultiMarkdownLuckily for me, salvation came and it arrived in the form of MultiMarkdown, a simple syntax to markup your text without the unnecessary bloat of xml. With this and a combination of other tools, you write your documentation once and export it to the multitude of supported formats. The diagram below provides an overview of the process for taking your text and transforming it into PDF and HTML. As you can see, I did end up using a small bit of XML technology (specifically XSLTs) to generate a table of contents from my MultiMarkdown XHTML output.
To get started, all you need is something to convert your MultiMarkdown documents into the desired format. For this task you can either download pandoc, or the conversion scripts from the creator of MultiMarkown’s site. Although pandoc looks like a promising tool, I personally had trouble installing it on my computer because of issues with macports & ghc.
Typing the DocumentationOne of MultiMarkdown’s best feature is its simple-to-learn syntax. It’s so intuitive, you don’t feel like you’re learning anything new at all. Below are a few commands to help you get started. For further help in TextMate, use the Control+H key combo to pull up the built in cheatsheet.
# This is an H1 tag ## This is an H2 tag ### This is an H3 tag ... And so on [This is a Link](http:\\www.google.com) ![This is an Image](my_image.jpg) CSS: style.cssThe last command, “CSS: style.css” tells the MultiMarkdown converter to link up style.css to the converted html file. I like to include it at the very top of any markdown document so that I can later stylize it with my own custom CSS.
Converting To Stylized HTMLConverting your MultiMarkdown to html is a simple process:
- Run multimarkdown2XHTML.pl provided in the “bin” directory of the MultiMarkdown distribution to transform your text.
multimarkdown2XHTML.pl file.markdown > file.html
- Add a table of contents using xsltproc and xhtml-toc-h2.xslt
xsltproc xhtml-toc-h2.xslt file.html > file_with_toc.html
- Stylize your final HTML with some nice CSS. Here’s the CSS that I’ve used for my own documentation. It’s a modification on the oh-so-beautiful FreeBSD documentation theme.
Converting to a Beautifully Typeset PDFConverting to PDF basically follows the same path, just with some different tools.
- Run multimarkdown2latex.pl provided in the “bin” directory of the MultiMarkdown distribution to transform your text into LaTex.
multimarkdown2latex.pl file.markdown > file.tex
- Add some LaTex formatting options if needed. For example, I added the following options to prevent indentation at the beginnings of paragraphs.
- Use pdflatex to turn the output from the previous step into a PDF.