Writing Scientific Papers Using Markdown


Writing Scientific Papers Using Markdown

Markdown is a markup language that is very handy and easy to use. I won’t say much more about it, but I’ve written about it before here and here. I’ve used it increasingly for writing blog posts, webpages, taking notes, with GitHub issue tracking, and with R code (R Markdown in RStudio is fantastic!). As a Mac OS user, I find Microsoft Office products to be annoying and temperamental. I read Karthik Ram’s great post on how to ditch MS Word a while back and since I’ve been using Markdown for so much lately, it seemed like a good time to write my first scientific paper with it. I’m going to use this post, written in Markdown, to outline my process. This will help me repeat the process in the future if I like it and hopefully help others interested in trying it.

Step 1: Create a Markdown Document

Obviously the first step is to create a Markdown document. You can do this with any text editor and just change the extension from .txt to .md. However, there are applications with handy Markdown features. I use Mou because it has a nice live-rendering of your markdown code so you can see what it looks like.

For this example and for future use, I’ve created a template for a manuscript that you can find here.

Step 2: Add In-Text Citations

To add references, I use Mendeley and create a folder for any publications I cite (or might cite) in the manuscript. Then while writing you can add in-text citations with [@Hocking2013], which can be found under Citation Key in Mendeley. Then I export this folder as a BibTeX file to the folder that the manuscript will live in. This will be used later to render the literature cited section.

Step 3: Install or Update Pandoc

Pandoc is an amazing program to convert between different file types. In our case we can create HTML, Word, and PDF files from our Markdown document. You can find the installation instructions at http://johnmacfarlane.net/pandoc/installing.html. You will also need LaTeX installed if you want to output PDF documents. You can use MacTex or BasicTeX on a Mac or MiKTeX on a Windows machine (Linux users, you know what to do).

I was getting an error

Error running filter pandoc-citeproc
Error 83

So I decided to install Haskell and run the following:

cabal update
cabal install pandoc pandoc-citeproc

Then this can just be run again in the Terminal app in the future to update pandoc.

Step 4: Add a Style Sheet

When creating a PDF there is a 1.5 inch left margin by default (good for binding I guess). Generally, I want 1 inch margins all around so I open a text file and paste

\usepackage[vmargin=1in,hmargin=1in]{geometry}

Then save it as format.sty in the folder with the manuscript. If you want line numbers and other formatting you can add these lines

\usepackage{lineno}
\linenumbers
\usepackage{times}

Step 5: Add a Journal Style File

One of the benefits of writing in simple text is that you don’t have to worry about formatting while writing. But now to add formatting for a specific journal, go here to get a style .csl file that is an XML type document that defines the styles required for a journal. This includes in-text citation, literature cited, and heading styles. Copy the desired .csl file into the same folder as manuscript .md document.

Step 6: Put it all Together

Now is when we use pandoc to combine the styles and bibliographic information with the manuscript. In the Terminal you can simply run

pandoc document.md -o document.pdf

to convert the document from markdown to PDF. However, this won’t have any of the desired formatting. To include the formatting, you just add some flags and arguments as such:

pandoc document.md -o document.pdf --bibliography cite.bib --csl style.csl -H format.sty

To automate this code and potentially output PDF, Word, and HTML documents all at once you can easily create a make file. To do this open a text editor and paste something like:

all: document_ms.pdf document_ms.doc

document_ms.doc: document_ms.md document_refs.bib
    pandoc -H format.sty -V fontsize=12pt --bibliography document_refs.bib --csl=ecology.csl document_ms.md -o document_ms.doc

document_ms.pdf: document_ms.md document_refs.bib
    pandoc -H format.sty -V fontsize=12pt --bibliography document_refs.bib --csl=ecology.csl document_ms.md -o document_ms.pdf

Then save the file as makefile with no extension (i.e. .txt). Then when you cd to that folder in Terminal you just have to type make and the documents will automatically be created. At this point you should have .md, .doc, and .pdf files (and .html if you want).

If you change anything in the markdown file or want to format for a different journal just add the new .csl file and make any other changes you want then run make again. Then submit the manuscript.

I am currently using diff in git or GitHub to replace track changes with co-authors early in the process when there are lots of changes but authors can also comment on Word or PDF versions as well. I’m also interested in potentially checking out Authorea for collaborative writing in Markdown. It seems pretty slick.

All the information for this post can be found at: https://github.com/djhocking/Markdown-for-Manuscripts

Advertisements

5 thoughts on “Writing Scientific Papers Using Markdown

  1. Thank you for sharing tips on academic writing, they look helpful!
    In fact, I’ve enjoyed many of your posts here and look forward to reading your next! 🙂
    Feel free to check out my writing about publishing: publishinginsights.org
    Sherry

  2. Pingback: Markdown for Manuscripts: Enhancements | Daniel J. Hocking

  3. If you like to write in Markdown and need to use citation, have a look at Texts (www.texts.io). It supports all the styles, required in academic writing.

  4. Thank your for this wonderful post. Citation works fine here, but I am wondering how you are working with tables and figures. Specifically, how do you insert captions and in-document references to them. I could fine any straight-forward way for this yet 😦

    Any help is highly appreciated!

    • I’m not exactly sure what you’re trying to do. For figures, I make them in R (or another program), then insert them as objects in the document. That way any captions are done as part of the image. Alternatively, captions as needed by publishers are usually just put as text in a special section at the end of the document. This goes for figures and tables. I am not sure how to create a reference within the document to a table or figure that links to it directly. Since markdown handles LaTeX and HTML code, I expect there is an HTML solution to creating the link but don’t know offhand. Good luck.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s