Writing Papers with Pandoc

At Daily Nous, there's a discussion of Tech Advice for a New Philosophy Grad Student.  There's some dispute about whether or not it's worth learning LaTeX.  I recommend pandoc instead for those who are on the fence.  You write in markdown, a simpler and more readable plain text syntax (compare *markdown italics* to \emph{LaTeX italics}, for example!). But it subsequently uses LaTeX to produce good-looking PDFs.  Or it can just as easily convert into other document formats, such as Word .docx, if needed.  It's very flexible.

You'll need to install:

(1) Pandoc

(2) A LaTeX distribution, e.g. MikTeX, if this isn't already installed with pandoc.

(3) A BibTeX bibliography manager.  JabRef works for me.  Create a single master bibliography with everything you ever want to cite (you can, of course, add to it later), and pandoc will pull in entries as you need them.

(4) A text editor.  I use Atom, with the extra packages (added under settings): 'autocomplete-bibtex', 'language-pfm', 'wordcount', 'markdown-writer', and 'markdown-preview-plus'. Set your OS to open .md files with Atom by default.

(Autocomplete for citations is great.  I start writing "@Par" and the text editor shows a list of all the Parfit entries in my master bibliography, so I can easily pick the right one without needing to have memorized the full reference label. And, as per standard pandoc citations, "[@ParfitRP]" in my text file becomes "(Parfit 1984)" in the compiled PDF, with the full bibliographic details automatically added to the References section at the end of the document.  When writing the paper, I don't have to look up a thing.)

Once that's all set up, you'll want to make a pandoc template with the standard header code that you'll use to start off all your papers.  I offer an example below, which includes some fake text to demonstrate some common markdown syntax, plus a bit of extra LaTeX code at the end to format the references nicely.

It may look intimidating, but aside from updating the text in ALL CAPS, you only need to learn the pandoc-markdown syntax, i.e. the stuff between the introduction and conclusion.  The full user guide is here, but my sample text demonstrates the main things you'll need to know, e.g. sections, citations, and footnotes.  Other than that, you can mostly just write, using asterisks for *emphasis*.

To actually produce a PDF (or whatever output) from your markdown text, you'll need to run pandoc from the command line.  In Windows, use File Explorer to browse to the folder containing your .md text file, hold SHIFT and click the right mouse button to display a menu from which you can select 'open powershell window here'.  Then copy and paste the running code (included in a comment at the bottom of the template, below -- the line starting "pandoc" and ending with "TITLE.pdf") into the powershell window and hit ENTER.  It should then create your PDF.

Feel free to borrow the following pandoc-template.md:

---

title: PAPER TITLE
author: YOUR NAME
thanks: Thanks to X, Y, and Z for helpful comments.
date: \today
abstract: \noindent YOUR ABSTRACT.
output: pdf-document
papersize: letter
fontsize: 11pt
documentclass: article
linestretch: 2
fontfamily: librebaskerville
link-citations: true
linkReferences: true
indent: true
...

# Introduction {-}

Test citation [@ParfitRP]---em-dashes---and soon a footnote.^[This is an inline footnote.]  I discuss this further in [@sec:LABEL].

# SECTION TITLE {#sec:LABEL}

As @ParfitRP[p. 131] explains:
> Here is a blockquote. *This sentence of it is italicized.*

## SUBSECTION TITLE

# Conclusion {-}

\newpage

# References {-}

\setlength{\parindent}{-0.2in}
\setlength{\leftskip}{0.2in}
\setlength{\parskip}{8pt}
\vspace*{-0.2in}
\noindent

<!-- this is a comment containing the running code to paste into the command line:
pandoc -s -N --filter pandoc-crossref --bibliography 'C:\PATH\TO\YOUR BIBTEX BIBLIOGRAPHY.bib' --filter pandoc-citeproc TITLE.md -o TITLE.pdf
-->

But again, don't be put off by all the code. You can play around with it if you enjoy that, but the whole point of the template is to take care of the background code for you, so you can focus on writing your paper.  And aside from the citations, the rest of your paper will mostly look like straightforwardly comprehensible plain text.

Like LaTeX, Pandoc isn't for everyone.  But I hope this info is helpful for some.  For additional background, see Thomas Hodgson's blog post, 'Try Pandoc instead of Word for your research writing'. For a more detailed tutorial, see here (via J. Adam Carter).