Pandoc is a command line tool that transforms one text format (like Markdown or reStructuredText) into another (like HTML, PDF, or Word). I primarily use it to transform my markdown source files into pretty things like web pages or PDFs that are ready to be printed out. Pandoc is more suitable to my needs as an academic than other markdown tools because it allows for necessary extensions of markdown like footnotes, bibliographies, and tables without becoming too unwieldy. Pandoc’s template system also means that I have full control over my output—although the defaults are pretty good when I just want to spit something out in an unusual format.

After installing Pandoc, you can simply run it from a command line (like Terminal or iTerm in OSX or cmd.exe or Cygwin in Windows). The basic usage is simple:

pandoc -o myOutputFile.docx myInputFile.md

Here the -o flag just means “output” and the filepath after it specifies the name of the file you want to create. Pandoc will automatically detect which format you want to go from and which format you want to output just by the file extensions you give it. In my example, I’m going from a markdown file to a word file.

So far so good, but what if you want to take advantage of those cool things like automatically formated bibliographic footnotes? Simply add the appropriate flags with the necessary information.

pandoc --csl=myChicagoDefault.csl --bibliography=myBibliography.bib -o myOutputFile.docx myInputFile.md

In this example the --csl flag specifies a file with the CSL-style specification for how footnotes and bibliographic entries should be formated and the --bibliography flag specifies a file containing my BibTeX database of bibliography information. You can get more information on my exact set up in this post. Other flags I often include are --smart for transforming straight quotes into curly quotes and hyphens into dashes and --chapters for making first level headers in markdown into chapters in my dissertation.

At this point it becomes somewhat unmanageable to type all these flags in every time you want to get a Word version of the essay you’ve been writing. Luckily, I rarely open up the command line for Pandoc. Instead, I just save the command I use together with all the flags as a “build system” in Sublime Text.

Here’s the build system that I use as a Gist:

Using this I just press Ctrl+Shift+B and I get a menu with the various output formats. I just select one, using either the mouse or the arrow keys, and out pops a new version of the file that I have focused in Sublime. The new file has the same name as the markdown version except that the extension is different.