Since I started using github in a serious way back in January I’ve begun writing my documentation in the markdown format that displays so nicely on github. Markdown is essentially a parsing tool and a simple text syntax that allows the easy conversion of human ‘readable text’ to html. It’s intuitive, it took less than 5 minutes to pick up, and saves me a ton of time not writing HTML. However, its ease of use is tempered, a bit, by a lack of features. Although it is easy to create headers, lists, and code bocks – simple HTML stuff – it doesn’t include the option to create tables, formated mathematical formulas, citations and bibliographies. Since I’m a scientist who wants to produce documents with these sorts of features, this is annoying.
Luckily, the markdown syntax has recently been extended, in a project called MultiMarkdown, to include many of the aforementioned features. Multimarkdown essentially merges the markdown syntax with LaTeX which, if you haven’t heard of it, is a rather inscrutable, but extremely powerful text formatting language. It’s popular in the CS and physics disciplines. LaTeX produces beautiful documents, but it’s easy to spend a week or more adjusting the formatting and reading the API trying to figure out some of the more complicated features. Multimarkdown looks like it will do much of the more basic LaTeX formatting, but without the headache.