Git-Pandoc Academic Workflow

A brief intro to some useful office apps for academics

Most readers probably want to skip this post. But for any tolerably tech-savvy grad students or academics out there (e.g. someone otherwise tempted to learn LaTeX), you might want to consider setting aside an afternoon to learn how to use Git and Pandoc. The initial set-up process—described below—is a bit involved, but after that it’s actually very simple. (Of course, none of this is strictly necessary—the gains over MS Word + Zotero + Dropbox are probably fairly minor. But this is the overall best system I’ve found yet. And it’s all free.)

Why Git?

Git offers online backup and sync and version control. If you want to try rewriting a section of your paper, but aren’t sure how the changes will work out, you no longer need to manually save a backup. Just create a new “branch” to work in for a while. You can switch back to your “main” branch at any time, and if you make independent changes in the main file, you can “merge” these into the side-branch rather than trying to manually copy & paste just the right changes to keep two separate documents in sync. So it offers an especially safe way to try out experimental changes, without risking either losing or unnecessarily repeating any of your work.

Academics may find it especially useful to create an “anonymized” branch for their paper, so that—when dealing with journal submissions and R&Rs—you (again) don’t need to worry about keeping two different documents (one anonymized, one not) in sync. You can make all your needed revisions on the main branch, and then just pull them into the anonymized branch before re-submitting your paper. It’s very neat!

Why Pandoc?

Pandoc (by philosopher John MacFarlane) is a powerful command-line utility for converting between different file formats. Pandoc-flavored Markdown offers a simple way to represent formatting while writing in plain text. Pandoc thus allows you to convert plain Markdown text into lovely, LaTeX-powered PDF output (or lamer-looking DOCX, or HTML, or…).

Some advantages of this include:

• Plain text files are universally readable and future-proof. (Whereas who knows what other file formats will still be used 50 years from now?)

• Entering citation details is so easy. When set up as per below, you can just start typing, e.g., “@Par” and it will list all the Parfit entries from your master bibliography, from which you can easily select ‘ParfitRP’ to cite Reasons and Persons in author-year format. Bibliography management is automatic: the full citation details will appear neatly in your ‘References’ section,¹ without any further effort on your part.

• Apparently you can instantly switch bibliographical styles by adding a line like “csl: mla.csl” to the header of your file (after you’ve added the mla.csl style file to your working directory; you can download CSLs from here).

• Internal cross-references (e.g. to section numbers) automatically update when you add new section headings or move them around.

  • I don’t think pandoc natively accommodates cross-references to footnotes yet. (But you can just add LaTeX code to do it.)

• LaTeX offers many similar advantages, but Markdown is easier (and far more readable) to work with than LaTeX code, and the output PDF looks just as good.²

Like LaTeX, working in Pandoc-flavored Markdown 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). Feel free to suggest other resources/tutorials in the comments.

Programs to install:

• MikTeX (or another LaTeX distribution)

• Pandoc and pandoc-crossref (extract the latter into your Pandoc directory)

• VS Code (then install extensions: pandoc citer, vscode-pandoc, and perhaps markdown meaningful word count, and markdown footnotes; others might use markdownlint and pandoc markdown preview)

• Git

• Jabref (or another BibTeX bibliography manager)

One-time setup

After installing the above, set up Git by entering your details using a command line terminal (e.g. Powershell):

$ git config --global user.name "John Doe"
$ git config --global user.email johndoe@example.com

Create a github account, and then log in to it within VSCode. Create a new private repository,³ containing the following files:

• Your bibliography.bib file (feel free to use my one for starters, and as you go simply add whatever further citation details you need—e.g. PhilPapers offers one-click export of a paper’s citation details in BibTeX format, which you can then easily add to your bibliography.bib via Jabref).

• A plain text starter.md file, something like the following:⁴

---

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

# 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

Next, still within VS Code, go to File → Preferences → Settings, search for ‘pandoc’, and in the fields for both ‘Pandoc: Pdf Opt String’ and ‘Docx Opt String’, enter the following:

-s -N -F pandoc-crossref --citeproc

Phew! That’s the one-time setup taken care of. From now on, you can simply…

Write your paper

To write a new paper, create a new PAPER-TITLE.md file in your repository, and paste in the contents of your starter file. Update the ALL-CAPS placeholders as necessary, then simply write your paper within VS Code using pandoc-flavored markdown syntax, as illustrated in the sample above (from the introduction through to the conclusion; don’t touch anything below the ‘\newpage’).

After major changes, or just whenever you want to back up your work, go to the ‘Source control’ tab on the left sidebar, enter something in the ‘message’ box to indicate what changes you’ve made (e.g. “expanded section X”), and then Commit & Sync it to github. I gather you can later “revert” specific commits if you decide that you don’t like those changes after all. But if you ever antecedently expect that you might want to revert a planned change, consider creating a branch for the experimental changes instead. It’s very easy to switch between branches.

To generate a PDF using pandoc on your markdown file within VS Code, just press CTRL-K, followed by P, and then ENTER to select ‘pdf’ output. Boom! Done.

Any other suggestions?

I’m far from an expert in this; I fudged together the above workflow via a mix of half-understood reading and trial-and-error.⁵ So if anyone with more tech expertise has better suggestions for any of this, feel free to share your recommendations!

1. Note that these won’t be visible in the markdown file, only in the generated output file.

2. Typically, pandoc requires use of the command line each time you want to generate your PDF output, which could be an extra barrier to some; but my VS Code setup avoids this.

3. I first created my repository on Github, and then used VS Code’s git commands to “clone” it on my local computer. But you might find it easier to just create it using VS Code from the start.

4. My sample starter file contains more than is strictly necessary, to illustrate some Pandoc-flavored markdown syntax, for reference. I’ve also added some LaTeX formatting commands at the end to make the references look nicer, but you can ignore that part.

5. I’ve used pandoc for writing philosophy papers for a couple of years now, and LaTeX for several years before that; but just switched to git and VS Code today, after enjoying using them for version 2.0 of utilitarianism.net.