Huy Nguyen

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 MultiMarkdown

Luckily 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 Documentation

One 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.css

The 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 HTML

Converting your MultiMarkdown to html is a simple process:

1. Run multimarkdown2XHTML.pl provided in the “bin” directory of the MultiMarkdown distribution to transform your text.

   multimarkdown2XHTML.pl file.markdown > file.html

2. Add a table of contents using xsltproc and xhtml-toc-h2.xslt

    xsltproc xhtml-toc-h2.xslt file.html > file_with_toc.html

3. 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 PDF

Converting to PDF basically follows the same path, just with some different tools.

1. Run multimarkdown2latex.pl provided in the “bin” directory of the MultiMarkdown distribution to transform your text into LaTex.

   multimarkdown2latex.pl file.markdown > file.tex

2. Add some LaTex formatting options if needed. For example, I added the following options to prevent indentation at the beginnings of paragraphs.

   \setlength{\parindent}{0em}

3. Use pdflatex to turn the output from the previous step into a PDF.

   pdflatex file.tex

If you’re lucky enough to have TextMate, all of these conversion scripts  mentioned above  are prepackaged in the “MarkDown” bundle for you.

Final Thoughts

So there you have it. With MultiMarkdown, you write one document and transform it into PDF and HTML with some basic tools. Overall, the format is concise, easily readable in raw format, and easy to maintain since it’s just plain-ol text. It is versatile, and has a mature set of tools to work with it. I’ve come to love it just as the creator of TextMate, and many others have. For small to medium sized projects, it’s the perfect documentation tool.

If you’re wondering what the final results look like, I wrote this article in markdown. Here is a sample of the Markdown, PDF, and XHTML that I generated.

See Also

• Writing Great Documentation – What to Write
• MultiMarkdown’s Main Site
• MultiMarkdown Scripts
• Pandoc
• My Custom CSS for Documentation
• PDFLaTex
• LaTex Formatting Options Tutorial