I have for a long time been a fan of writing everything as plain text. This started with me using LaTeX, which I still do when I want a perfectly formatted result. However, the last few years I have taken to using some of the many Markdown variants available. This has several advantages: First and foremost, the source is perfectly readable as-is, which makes it ideal for readme files and the like. And you can generate multiple output formats, depending of course on what markdown variant you use.

I initially started using Asciidoc, which is really good, and can generate output in HTML, PDF, ODF, and several different slideshow formats. However, it is not based on standard Markdown, but uses it’s own slightly different syntax. This is annoying if you sometimes also need to use normal Markdown. Recently I have switched to Pandoc, which is based on MultiMarkdown syntax with some extensions. It can generate oodles of different output formats, several of them text based, which for instance makes it easy to write MediaWiki pages. I always have problems remembering MediaWiki’s fiddly syntax, and having to write things like '''''bla''''' just makes me cringe.

Each format can take many configuration parameters. If I want multiple output targets, I usually use a make file, something like this:

Another format supported by Pandoc is Json, which can be used for both output and input. The Json structure essentially contains the internal parse tree of the document, which makes it useful for custom filters and such. Pandoc is written in Haskell, and as a good opportunity to write my very first Haskell code snippet, I thought I’d try to make a filter for Takeshi Komiya’s neat Blockdiag. Here it is:

You just put your diagram source in a standard Pandoc code block, tagged like so:

~~~~ {.blockdiag} 
blockdiag { 
  // branching edges to multiple children 
  A -> B, C;

  // branching edges from multiple parents
  D, E -> F;
}
~~~~

You then call it like this:

pandoc -t json test.md | handleBlockdiag png | pandoc -f json -o test.pdf

And get this result. Works great!