[Subscribe to the Recursive Labs email Newsletter to get updates][Find out more about our online courses] [Connect with us on Twitter][Facebook Page]

Pandoc, an amazing Haskell tool for writing documentation

May 26, 2012

I was looking around for a tool to write my RTOS Guide; I had experience using LyX and Sphinx and I loved both. The notes for my introductory embedded systems course were written completely using LyX and my Python/LaTeX book was written using Sphinx. But this time, my requirement was a bit different - I wanted an easy way to generate HTML and PDF from a single document.

Both LyX and Sphinx are capable of doing this, but I wanted to try something different. Pandoc seemed to be a good option. It is written in Haskell - one of the only two Haskell tools which I have ever used; the other one being the tiling window manager xmonad. The Pandoc home page describes it as the "swiss-army knife of document format converters" - and that is exactly what it is!

Here is a small example - a document written in Markdown (pandoc has it's own form of "extended markdown"):

% An example Pandoc document
% Pramode C.E
% May 26, 2012

# First level heading #

This is a sample markdown document.

## Second level heading ##

This is a list:

* one
* two
* three

To convert this to pdf, simply run:

markdown2pdf a.txt

"markdown2pdf" uses "pandoc" and "pdflatex" to generate pdf output.

To get HTML output, run:

pandoc a.txt -o a.html

Pandoc generates plain HTML output - you will need to "style" this so that it matches the overall theme of your website. This is extremely simple.

For example, I need to add a "footer" to all my html pages (before the "</body>" tag) - this "footer" is some javascript code for the "disqus" comments system. I can do this very easily by running:

pandoc a.txt -o a.html -A footer.txt

"footer.txt" contains the js code; it gets added to the end of "a.html" just before the "</body>" tag.

Similarly, I can add text at the end of the header, or as the first part of the body (immediately after the "<body>" tag). Many other customizations are possible with custom templates. The slightly modified markdown syntax makes it possible to add stuff like footnotes (to the pdf output) and id/class markers to html elements.

If you are planning to write some documentation, give Pandoc a try - you will love it!

blog comments powered by Disqus