Writing workflow: Markdown, Pandoc, LaTeX and the likes


Toni Verbeiren


June 24, 2013

You wouldn’t tell from the updates on this website, but I’m actively writing again. Offline, that is, the online part is for later. For now, I want to share my experience improving my writing workflow.

In the past, I used LaTeX for scientific texts and MS Word for everything else. LaTeX gives me the professional and typographically correct texts that I want, but I spent too much time fiddling around with packages, remembering markup, etc. MS Word, on the other hand, quickly made me get things done, albeit without the professional look or scientific powers.

I’m now in a situation that any writing (technical, scientific and even prose) can be done in the same way, delivering results in PDF, html or even MS Word:

  1. It usually starts in iA Writer (on the Mac or the iPad), but any word processor able to handle ASCII text can be used. I choose iA Writer because of its distraction free writing.

  2. Markdown is used as markup specification (including figures, footnotes, emphasis, etc.). Markdown is very basic, but it lets you focus on the content, rather than the form.

  3. Programming code (R for instance), formulas, etc. can all be included in the Markdown format by means of the proper notation and possibly some extensions to the parser (see step 4).

  4. By means of Pandoc, the text is converted into the appropriate format (html, pdf, LaTeX, ePub, DocBook, …)

  5. Ready!

Ok, I hear you thinking, but you just lost all possible configuration of look and feel, layout, etc… That’s correct, there are some Markdown writing tools that allow you to create PDFs that look awful.

The nice thing about Pandoc though is that during the conversion step (4), you can specify the templates (CSS, LaTeX header code, MS Word template) that should be used.

It takes some fiddling in order to get the correct options to Pandoc and get proper templates in place. A Google should get you going.

A similar process is used to create the reports for the different analysis steps for the dataMineR project.