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 20-30 minutes to install the necessary software:
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):
“dictionary”: “Packages/Language - English/en_US.dic”
//location of the bibtex file:
“search_fields”: [“author”, “title”, “year”, “id”],
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:
$ 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
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