Using (R)Markdown to write papers of all flavors

Nov 24, 2017 00:00 · 946 words · 5 minutes read #Rstats r markdown sublime pandoc

The core idea - make writing as simple as possible

When I decided that I’ll move to a “One Text Editor - All the tasks” approach LaTeX was the first thing I set up (and wrote a quick post about it). Since then a lot of things happened that altered how I write: I created this blog with the awesome Blogdown, my research project arrived at a phase where I use R frequently (and document my things in R Markdown) and finally I write everything in Markdown now, except my dissertation which is still in LaTeX (and probably will stay that way).

Some key elements that informs my workflow:

  • simple solutions over complex ones
  • eliminate clutter; writing is hard enough as it is, don’t make it harder
  • Markdown and a great text editor is all you need (my choice is SublimeText, but there are others)

Write in Markdown and have the output in PDF

TL;DR

  1. Write your text in Markdown
  2. Specify pdf output and bibliography in your YAML header
  3. Use pandoc and pandoc-citeproc to convert your Markdown document into a pdf with citations and bibliography at the end
  4. Never look back.

Alternatively, if most of the stuff you do is in R, just use the wonderful R Markdown within RStudio and proceed from step 2., or setup your text editor as an R IDE and write your .rmd inside that.

1 - Using RStudio and R Markdown

Markdown is a simple, easy to read and easy to write language that was created initially as a text-to-HTML tool. You can find a great guide at GitHub or use the cheatsheet by Adam Pritchard. As you see, the syntax is easy and the html output looks great. So far so good. The problem that I run into was that I needed PDFs and I needed Markdown to handle citations and build a reference list. As Markdown was built for html output these things are not self-evident. Around the same time I was playing around a lot with R Markdown, which is an excellent way to create teaching material, reports, and reproducible research in general. And the more I looked into it, the more intrigued I was: RStudio could knit my .Rmd into either html or PDF and through using pandoc you can have your citations and references in your document.

You have to have your .bib file in the same directory as your .md or .rmd and specify in your Markdowns’ YAML metadata section, which looks like this:

---
title: My paper with citations
author: Takeshi Kovacs
output: pdf_document
bibliography: biblio.bib
---

RStudio has an excellent guide on what you can put into the YAML header, it is worth a look.

Now all you have to do is knit your R Markdown document into a pdf. The RStudio interface got a huge upgrade and now looks slicker than ever, so it definately can be used as your Markdown editor. Just fire it up, and open a new R Markdown document. It is primarily geared toward working with R and R Markdown (duh) so if you have writing needs centered around R output then look no further. (or maybe setup your text editor to serve as an R IDE as well). If you write things that does not involve R output however, then combining pandoc and a good text editor might be the way forward.

2 - Using text editor and pandoc

If you want to set up a minimalistic and disturbance free writing environment with the above mentioned output goals it going to be a little more work, but will worth the tinkering. This example is for Sublime as this is my go to text editor. The setup is a straightforward process. The Markdown package that I use and can recommend is the MarkdownEditing that supports the Standard Markdown, GitHub flavored Markdown, and MultiMarkdown. It also comes with light and dark colorschemes, but you can always get more.

Step 1 check.

To convert your Markdown into pdf you need to get two things. First, you have to install Pandoc. Pandoc is a document converter that converts everything into everything. Yes. After you installed the 9th wonder of the modern world that is Pandoc, you just need to install the corresponding Sublime package: sublimetext-Pandoc.

For configuring the Pandoc Sublime package, see this excellent guide in this post. That post also details a similar workflow so you can give that a try as well.

Now everything is set up, the Markdown document with the correct YAML header is ready, the .bib file is in place. You can cite with the [@citation-key] syntax. Now type “Pandoc” in the Sublime command palette (ctrl+shift+P on Windows) and select the output format.

---
title: my paper with citations
author: Takeshi Kovacs
output: pdf_document
bibliography: biblio.bib
---

This should have all the citations as [@sakurai1995modern] discussed.
And at the end, just insert the reference list.

#References

Step 3 and 4 check.

If you want to tweak the LaTeX output, you can do it as well. The extensive post of Kieran Healy details this process and you can check out how to set up that custom LaTeX style file.

Finally, to get that distraction free writing feeling. If you use Atom, Sublime, Vim or Emacs (I haven’t checked the rest) for text editing you can switch to a distraction free mode (or have a plugin to do it). If you want to go all in on the experience, you can use the Typewriter package for Sublime, that will vertically center the line you write. No more looking at the bottom of your screen for hours. The final results is something like this in Sublime:

step 5

step 5