In a series of previous posts (1, 2, 3, 4, 5), we learned about using Markdown and Pandoc to write research-related documents. A key type of document that we have not covered is scientific articles.

Available options

I have looked on-and-off for a few years now for a simple tutorial of how to prepare a scientific paper using only Markdown and Pandoc. There are many tutorials online, but none of these rang true. Some were rather sophisticated, requiring the use of Pandoc filters programmed in Python, while others were based on the very popular RMarkdown and knitr, used and loved by many researchers who use R to do their work (and writing!).

Based on what I have learned, it is possible to write papers in Markdown that, when paired with the appropriate LaTeX template document and associated files, will look just like an official publication. That is, they will be based on the official LaTeX style provided by the journal (e.g. PLOS ONE) or publisher (e.g. Elsevier, Springer). This is already possible if you use RMarkdown and knitr. However, I currently don’t use those tools, and don’t feel like learning them simply to write my papers.

Therefore, based on what I learned, I created a generic article style that should be suitable for most of my papers (and hopefully some of yours).

A generic Markdown-Pandoc scientific article

The repository containing the files required to write the article are located on Github. Rather than write a long blog post containing all the details, I decided to write the details right into a manuscript! The Markdown version of this manuscript, manuscript.md, shows you how I entered the text to be able to generate the nice looking PDF output.

The PDF output (and the Markdown file) provides a detailed explanation of how I went about setting up the various files, how you would use them to write a paper, and how you would change certain variables to alter things like reference style, section numbers, etc. If you are interested in reading the paper, but don’t want to (or don’t know how to) get it from GitHub, you can download the manuscript by clicking the download link below.

Next steps

I am interested in using this approach to draft my next scientific paper to see how well it works. I have already identified a few things that need to be solved, including easily generating a marked-up version of the manuscript after reviewer comments have been addressed. This should be easy to solve, and automating such a process should make it accessible to many more people.

I would also like to create a LaTeX template that can be used by Pandoc to generate a paper for a common journal style. PLOS ONE comes to mind a logical first choice. I will definitely be trying this in the future, and will write about here if I succeed!

Resources

A very good read and resource is the article entitled Sustainable Authorship in Plain Text using Pandoc and Markdown by Dennis Tenen and Grant Wythoff. It provides a good argument as to why, as academics, we may want to do use a simple, plain text approach such as Markdown and Pandoc to write our papers.