Blog

Documentation, Markdown, and Pandoc

We've been doing a ton of work on documentation around llamaville lately, and since many of us working here are programmer types, most of our doc systems are configured to use the Markdown markup language (link) for writing richly formatted content. This is great, with one small problem - our project management system doesn't currently support Markdown. It uses a WYSIWYG editor, or can take straight HTML input.

I strongly dislike WYSIWYG editors, as they are slow and difficult to work with in my experience, and writing HTML directly is also time consuming and laborious. Life has ben rough, until last night when I stumbled across a little gem of a program: Pandoc by John McFarlane (http://johnmacfarlane.net/pandoc/).

Pandoc is a beautiful little markup converter that can convert just about any common markup language to just about any other common markup language.

What this means is that I can take HTML input, convert it to Markdown for editing, and then convert the Markdown back to HTML for upload and input. This streamlines my editing process significantly, and makes my life as a documenter and scope write so much easier. In my experience so far, it has done a beautiful job with everything I've thrown at it, even gracefully taking some pretty ugly HTML and making beautiful, clean Markdown out of it.

Following is a sample command I use to grab HTML content from my clipboard, reformat it as Markdown, and spit it out in TextMate, my editor of choice:

# pbpaste | pandoc -f html -t markdown | mate

This would, of course, work for any format supported by Pandoc, which includes the popular Textile among other languages.

Cheers!

~Rob

P.S. I'm also evaluating a slick little Markdown editor I found called Macchiato. Check it out: http://getmacchiato.com/

Posted on August 30, 2011

Posted by Rob Tull

Add comment

The content of this field is kept private and will not be shown publicly. If you have a Gravatar account associated with the e-mail address you provide, it will be used to display your avatar.
  • Web page addresses and e-mail addresses turn into links automatically.
  • Allowed HTML tags: <a> <em> <strong> <cite> <code> <ul> <ol> <li> <dl> <dt> <dd>
  • Lines and paragraphs break automatically.

More information about formatting options