Pandoc

Pandoc is why you only have to write a document once

Pandoc reads a document into an internal model of its structure — headings, lists, emphasis, citations — and writes that model back out in whichever format you ask for. Write in markdown; hand the committee a .docx, the students a PDF, and the website its HTML, all from one file.

Pandoc

One-sentence definition: Pandoc is a command-line¹ tool, written by the philosopher John MacFarlane, that converts documents between dozens of markup formats² by reading them into a common structure and writing that structure out again.

Copying text from a PDF into Word and watching the headings, tables, and references fall apart is the problem pandoc solves. Pandoc works out what each part of the document is — a heading, a list item, a citation — and rebuilds it in the target format’s own idiom. A second-level heading in markdown becomes a Heading 2 style in Word, a \subsection in LaTeX, and an <h2> in HTML, and the reverse conversions work too.

What makes it more than a convenience:

• Citations. Pandoc reads a bibliography file (BibTeX, or exported straight from Zotero) and a citation style, and turns [@vleuten2012] in the source into a correctly formatted in-text citation and reference list in any of the thousands of CSL styles.³ Switching a paper from APA to Vancouver for a different journal is a one-word change.
• Templates. A .docx reference document or a LaTeX template controls the output’s appearance, so a plain markdown file can come out looking like the institution’s house style without any of that style living in the source.
• Scriptability. Because it’s a command-line tool, it sits inside automation. A module handbook can be rebuilt as Word, PDF, and web pages every time the source changes, without anyone opening a word processor.

Converting teaching materials between formats

Teaching materials are where this pays off, because the same content has to reach several audiences in the formats each one expects. A speech and language therapy placement handbook might go to practice educators as a Word document they can annotate, to students as a PDF, and onto the virtual learning environment as a web page. Kept as three files, the versions drift apart within a term; kept as one markdown source, a change to the assessment criteria reaches all three the next time the command runs.

The PDFs of the essays on this site are built the same way, with pandoc, from the markdown the web pages come from. Tenen and Wythoff (2014) walk through the basic workflow for an academic — markdown, a bibliography file, one command — and Healy (2014) describes a social scientist’s version of it; neither has changed much in a decade.

What pandoc leaves behind

Pandoc carries structure across and leaves layout behind. A complex Word document with floating text boxes and manual spacing comes through as its underlying content, which is usually what you want and occasionally isn’t. Conversions from PDF are poor, because a PDF records where marks sit on a page and says little about what they are, so it’s best treated as an output and never as a source.

Sources

• Healy, K. (2014, January 23). Plain text, papers, pandoc. Kieran Healy. https://kieranhealy.org/blog/archives/2014/01/23/plain-text/
• MacFarlane, J. (2006–). Pandoc: A universal document converter [Computer software]. https://pandoc.org/
• Tenen, D., & Wythoff, G. (2014). Sustainable authorship in plain text using Pandoc and Markdown. Programming Historian. https://doi.org/10.46430/phen0041