Nikola Sander

Barrett Riddleberger says we should take 6 pleasurable steps to eliminate procrastination: availability, atmosphere, attire, appetite, audio and actions. When it comes to academic writing, I suggest one more step: using an appropriate word processor.

I can take all the steps Barrett recommends, but when I stare at a blank MS Word page, all my good writing spirits suddenly fade away. I think of the hassle of formatting a Word document, of editing equations, of including references via plug-ins that never seem to work properly, and of adding graphics that somehow lose quality. Sigh.

LaTeX to the rescue? Well, I used LaTeX for a year or two with great passion, but now I’m not so sure anymore. LaTeX is a high-quality typesetting system that is great for writing papers with lots of equations, cross-references and complex formatting requirements. But for me, there is one main problem with using LaTeX as a mainstream word processor for academic writing: the code is not very clean. Setting the formatting and including graphics and tables requires lots of curly brackets, backslashes and begin & end commands. Such an elaborate code slows down the writing process and, perhaps more importantly, colleagues who are less familiar with coding may find LaTeX documents very intimidating. Collaborating with non-LaTeX users is further complicated by the fact that there is (at least to my knowledge) no straightforward conversion between LaTeX and Word. Not to mention that many journals still require you to submit your article in Word format.

So, what we need is a word processor, or a word processing workflow, that is based on clean, non-intimidating code, uses open-source software, requires little coding skills, creates & formats reference lists automatically, and is flexible in terms of the output format. Too much to wish for? Well, writing papers with Markdown+Pandoc gets pretty close! Bonus: you can use it on both Windows and Mac plattforms.

I’m not the first person to suggest writing papers in Markdown and converting to other formats using Pandoc, (you can read about it here, here, here and here) but I’m writing this blog post to spread the word - because I think it’s definitely worth a try!

To get started, you need to do two things:

• take 10 minutes to familiarize yourself with Markdown. The code is so simple, it won’t take any longer. Use the Dingus to get a feel for how the formatting works.

• take 20-30 minutes to install the necessary software:

  • install MiKTeX or another LaTeX system (you need LaTeX running in the background to convert Markdown to PDF)
  • install a reference manager (like Zotero or Mendeley or JabRef) and create a BibTeX file with all your references. I use Mendeley because it lets you specify citation keys and has a BibTeX Syncing function that keeps your BibTeX file up to date with the documents in your library.
  • install Pandoc
  • install Sublime Text 3.
  • install packages for Sublime Text 3:
    
    • install Package Control first (cllick on the link for details)
    • restart Sublime Text
    • open the command palette via the ctrl+shift+p shortcut or the Tools > Command Palette menu
    • to install a package, type “install” into the command palette, click on “Package Control: install package”, and type the name of the package into the console. Click on the package to install.
    • install these packages:
      • Markdown​Editing
      • Academic​Markdown
      • Word​Count
      • Citer
      • optional: Theme - Soda
    • all installed packages are listed in Sublime Text under the Preferences > Package Settings menu.
  • set the syntax to Academic Markdown (via the View > Syntax menu). You can also use MarkdownEditing > Markdown.
  • set the colour scheme to Academic Markdown (via the Preferences > Color Scheme menu)
  • edit the user settings for the packages via the Preferences > Package Settings menu. For each package, there is a text file with the default settings, and a text file with the user settings. Click on “user settings” to edit the text file.

  • I did the following edits to the user files. You can copy & paste these lines of code into your user file and go from there. The “ get replaced by some other quotation marks by copying and pasting, so you’ll have to do a find & replace with normal quotation marks once pasted into Sublime Text. Don’t forget to save the edited files.

    • MardowndEditing (Markdown Standard):
      {
      “draw_centered”: true,
      “extensions”:[“md”],
      “rulers”:[],
      “word_wrap”: true,
      “wrap_width”: 90,
      “spell_check”: true,
      “dictionary”: “Packages/Language - English/en_US.dic”
      }

    • AcademicMarkdown:
      {
      “draw_centered”: true,
      “extensions”:[“md”],
      “rulers”:[],
      “word_wrap”: true,
      “wrap_width”: 90
      }

    • Citer:
      {
      //location of the bibtex file:
      “bibtex_file_path”: “C:/Users/Nikola.Sander/Documents/library.bib”,
      //Citer Search:
      “search_fields”: [“author”, “title”, “year”, “id”],
      “citation_format”: “@%s”,
      }

Now, all you need to do is open a new file in Sublime Text and start writing. You can use this zip file with all essential files to create a basic paper. To add a reference in the text, you just use @ and the citation key. To search for the citation key within Sublime Text, open the command palette via the ctrl+shift+p shortcut, type “citer” and click on “Citer:Search”. A window opens at the bottom of the screen. Enter the search term (eg author name) and select the citation you want from the drop-down list. Separate multiple citations with a semicolon.

Save the paper as a Markdown file (.md) together with your images, your bibtex file and your citation style cls file in the same folder. Alternatively, you can specify the location of bibtex and cls files in the preamble of your Markdown file. The preamble is the grey-shaded top section of the template in which you specify the title, author, abstract etc, which get picked up by LaTeX and formatted into a title page. The preamble begins and ends with ---

Use Pandoc to convert the Markdown file of your paper to PDF or Word or html:

• Open the command prompt or terminal. I use Git Bash instead.
• navigate to the folder with your Markdown file and run pandoc to convert the file, for example:
  $ cd /c/users/donald.duck/sample-paper
$ pandoc -S -o sample-paper.pdf --filter pandoc-citeproc sample-paper.md
$ pandoc -S -o sample-paper.docx --filter pandoc-citeproc sample-paper.md
• note that I use the pandoc-citeproc filter option to process my citations
• you should find a pdf and a docx version of your paper in the same folder

The nice thing about this workflow is that you can set up an automatic formatting of the pdf and Word versions of your paper while keeping the formatting of your Mardowns files to a minimum. The trick: templates. The LaTeX templates have the file ending .latex and can be edited in Sublime Text. They look a bit like the normal LaTeX preamble. You can simply add a template to your project folder and run Pandoc with the –template option:

`$ pandoc -S -o sample-paper.pdf --template=template1 --filter pandoc-citeproc sample-paper.md`   
										

The templates for Word are basically normal .docx files with formatting styles. I haven’t yet worked out how to edit the styles properly in Word, though.

If you write a paper in Markdown and your collaborator makes edits to the Markdown file, you can use DiffMerge to see the changes.

I hope you found this introduction helpful. Send me a Tweet to @nikolasander if something remained unclear or if you have suggestions for improving the workflow!

Writing academic papers in Markdown using Sublime Text and Pandoc was originally published on 13 November 2014