05 February 2013

Write academic papers with Markdown + Pandoc

I have been for many years a LaTeX user (I wrote all my reports as well as my PhD thesis with it).

However, there is some things I did not like with LaTeX:

[1] Bibliography styles were sometimes hard (if not impossible) to find

[2] You had to work with someone who was LaTeX aware, or he/she would say that this is horrible to write something with all those weird things around blablabla

[3] Not very straightforward export to .doc when needed by journals

This made the use of LaTeX on an everyday basis very difficult and often discouraging when it was about collaborative writing.

However, I recently discovered the possibility to use Markdown+Pandoc

Markdown is an extremely simple syntax originally used to convert pure text to html (and extremely powerful for that) but is expanding rapidly (you can make slides but also reports including text, code and figures with R). What is nice with Markdown is that it can be used as a source to create documents in pretty much any standard format (thanks to Pandoc). But even nicer is that:

[1] It uses the CSL format for bibliography, which happens to also be used by all the new cool biblio management softwares like Mendeley, Zotero and Papers. So you can easily find all the styles you can possibly need (just go here, or here).

[2] The source document in plain text is already extremely readable (that is all the point, and what made the success of Markdown).

[3] It can export doc and pdf, etc (+ generate bibliography) with one simple command.

To get a pdf, it is as simple as:
pandoc mymanuscript.md -o mymanuscript.pdf --bibliography=../library.bib --csl=apa.csl

To get a .doc:
pandoc mymanuscript.md -o mymanuscript.doc --bibliography=../library.bib --csl=apa.csl

To get a pdf with as much layout flexibility as with TeX, etc:
pandoc mymanuscript.md -o mymanuscript.pdf --latex-engine=xelatex --bibliography=../library.bib --csl=apa.csl -H ../margins.sty
Where the file margins.sty contains the following line in order to get nice margin sizes:
\usepackage[vmargin=1in,hmargin=1in]{geometry}


However, there is still something I don't like with this kind workflow for academic writing: the collaborative part.

I'd like something as easy to use as Google doc (especially for the comments), but with a better visibility of modifications (as in Word), and the ability to properly get back to older version as in Git.

4 comments:

  1. You could try using CriticMarkup (http://criticmarkup.com/) for collaboration. It should work just fine with MultiMarkdown Composer 2.1.

    ReplyDelete
  2. Thanks for the suggestion. I just looked at it and it indeed looked really interesting!

    ReplyDelete
  3. git diff --word-diff shows a CriticMarkup-like output. Or, use a program like Kaleidoscope for your diffs.

    ReplyDelete
  4. Hey there! even though this is a (very) old post, I hope you still see this. I'm just starting out a PhD in Neuroscience and I'm having the same issues you had: I've been using LaTeX since high school but in my lab everyone is using Word and SPSS.

    My question is, after writing your paper in Markdown, how do you convert it to the paper's guidelines? I'm about to write my first paper and would like to optimize my workflow from the start.

    Thanks!

    ReplyDelete