I spent an hour this morning polishing up a proposal. This mostly involved running spell-checks, cleaning up tables, and making sure I added in all the right references. That’s when I realized something. I haven’t used Microsoft Word to write anything in over 6 months. How fantastic!

Like everyone else I’ve been complaining about MS Word since the last ice age but never had a better alternative. When Markdown came around I was smitten but there were several things missing. Tables were hard to format and I still had to get the final text back into Word to insert citations. I’m happy to report that I’ve found great solutions to both these issues. So here’s a quick how-to (following up from my earlier post) for switching your writing workflow away from Word. There is a small learning curve but the payoff is wonderful.

Software you’ll need

• Pandoc – It’s like the swiss army knife of document conversion. Although it’s command-line only, pandoc is easy to use and quickly converts any document into whatever format you desire.

• Mendeley – A free reference manager. Mendeley is great for two reasons. First, it allows you to collaborate via shared libraries (especially when writing with multiple authors). Second, Mendeley can automatically export those libraries to a bib file anytime you make changes to them. (update: You are free to use any reference manager. Just export a bibtex file to the folder containing your writing).

• A markdown editor (optional) – Technically you don’t need any special software to write in markdown. Any text editor will do. However, there are several tools and helpers that make the process easier and more fun to use. Marked for e.g. renders a live preview into one of several styles (or custom ones). If you’re on a mac, here is a complete roundup of Markdown editors. My favorites are iA Writer, and Sublime Text with the SmartMarkdown package. Mou is great for beginners.

• knitr (optional) – If you plan to insert data tables, either from a spreadsheet or if you need to incorporate summary statistics, knitr will run the code for you in R and insert the output in pandoc friendly format (with the help of the pander package). This step isn’t necessary if you don’t require tables. I’ll describe this process in more detail in my next post.

That’s it as far as set up goes.

Writing your document

The markdown syntax is super easy to learn. It takes all of 5 minutes to learn and the documents are easily readable even when unparsed (unlike LaTeX). Here’s a quick guide to markdown syntax. Here’s what a simple markdown document looks like:

# Title
some text. 
some more text.
## a sub-heading
More text. A [link](http://google.com/). 
A figure
![Figure 1: caption](figure.png)

This screenshot shows you unparsed and parsed markdown side by side.

Adding in citations

Now if you need to cite anything, first add documents to your Mendeley folder or group and have it automatically export to a bib file into the same folder as your document (see Mendeley desktop’s settings). To cite any document, look at the details pane for a citation key.

To cite this reference, add it in like so:

some statement [@Costello2009].
statement with multiple citations [@Costello2009; @Costello2010].

Generating a pdf

Now you can use Pandoc to turn this markdown file into any format you like. Word (docx), rtf, pdf, html, LaTeX, plain text. Just change the pdf extension to the output format you need.

The simple way:

pandoc document.md -o document.pdf

With citations:

pandoc document.md -o document.pdf --bibliography citations.bib

Formatting for a journal? Grab the citation styles from here and drop it into your folder. Then specify that style during document generation:

pandoc document.md -o document.pdf --bibliography cite.bib --csl style.csl

You can create a Make file for each project and run that instead of typing in the pandoc call into your terminal (although this is super easy to remember once you use it a few times). That’s really it. You can do a lot more like adding in results, tables, figures, and equations using mathjax but I’ll save the more advanced stuff for a future post.

Workflow

When starting any new writing project, I create a new folder with two files (my markdown document and a small script). If this folder doesn’t already sit inside a git repository, I initialize one so my writing is version controlled (to avoid this) from the very beginning. Version control makes it really easy to return the document to any stage, remotely back it up on GitHub (and or other locations), and edit asynchronously with multiple coauthors (all of which are impossible with Word). When I need the formatted version, I run the script which:
* Copies in the most current version of the bib file from Mendeley
* Parses my markdown with pandoc using the settings I need (citations, equations, margins) and outputs a pdf (for viewing) and Word (for some collaborators that still prefer this format).

Update: Here is a real world example of how I do this. Just click the zip icon to grab a copy and test this out for yourself.