Writing a Paper in Markdown (Part 1: Setup)

Markdown is a lightweight markup language for writing structured documents. You write plain text and use simple symbols to define headings, bullet lists, and text formatting.

You can write Markdown in any text editor, and many programming-oriented editors include a Markdown preview feature so you can see the rendered output as you write. Examples include VS Code, Atom, and Sublime Text.

These days I often write in Markdown for notes. When I’m already working in a text editor, it’s convenient to keep everything in one place instead of opening a separate app like Word. Word is powerful, but for quick drafts a lightweight editor often feels faster and simpler.

I recently learned that it’s possible to write academic papers in Markdown, so I decided to explore the workflow.

Sectioning using headings
Inserting citations
Inserting figures and tables
Text styling (italic, bold, superscript/subscript, etc.)
Equations (depending on the field)
Version history / change tracking

The requirements for writing a paper are not that many. I think Markdown in a text editor is sufficient for writing the manuscript itself. One advantage is that Markdown is text-based, so it’s lightweight and you can use your favorite editor. For example, using VS Code together with GitHub makes it easy to manage version history. You no longer need to save multiple files like manuscript_ver12, and you can view diffs between versions easily.

However, Markdown is not an easy format when you ask co-authors to review your paper. Also, for journal submission, you usually need to convert it to Microsoft Word format.

In this post, I tested converting from Markdown to Word at the final stage of the writing process. I also tried converting from Word back to Markdown, assuming a scenario where co-authors make comments or edits in Word.

Pandoc is an open-source tool that converts between many document formats, including Markdown, HTML, Microsoft Word, and PDF.

It is written in Haskell, and you typically use it from the command line.

MacBook Pro (macOS Catalina)
Text editor: VS Code

I tested this on a Mac. Aside from small differences in command-line syntax, the workflow should be almost the same on Windows.

I use VS Code as the editor, but other editors should work as well. The way you insert citations and the look of the Markdown preview may differ slightly depending on the editor.

You will need two programs: Pandoc and a reference manager (Zotero). As of January 2022, I used Pandoc version 2.16.2 and Zotero version 5.0.97-beta.63. Versions may differ today.

Pandoc

Pandoc converts Markdown files into Microsoft Word .doc/.docx format. It can also convert to other formats such as PDF and HTML. On macOS, if you have Homebrew installed, you can install Pandoc with:

brew install pandoc

You can also download Pandoc from Pandoc’s website without using the command line.

Zotero

Zotero is a reference manager used for citations. For downloading and configuring Zotero, please refer to this article .

You will need the Zotero plugin Better BibTeX . Configure it in Zotero Preferences as follows:

Preference/Better BibTeX/CitationKeys
  force citation key to plain text: checked
  enable citation key search: checked
Preference/Better BibTeX/Export/QuickCopy
  Pandoc citation
  surround pandoc citation with brackets: checked
Preference/Export/item format
  Better BibTex Quick Copy

If you use VS Code as your text editor, the extension VS Code Citation Picker for Zotero is very helpful for inserting citations into Markdown. As I’ll mention later, the extension Markdown Extended is also useful.

You will need several files. The folder structure looks like this:

User
  ├── Documents
  │       └── Manuscript
  │               ├── input.md
  │               ├── library.bib
  │               ├── custom-reference.docx
  │               ├── fig1.jpg
  │               └── pandoc_md2docs.sh
  └── Zotero
          └── styles
                  └── nature.csl

input.md

This is a template Markdown file. The section at the top surrounded by --- is metadata written in YAML format, which Pandoc uses (explained later). Copy the text below and save it as input.md .

The template also includes extra text, tables, and figures to test citations, text formatting, and inserting tables/figures.

---
title: This is the title
author:
  - Naoki Takahashi
  - Thelonius Monk
date: 01-16-2022
link-citations: false
link-bibliography: false
...

### Abstract

**strong** (**), __strong__ (__), <strong>strong</strong> (str)

*italic* (*), _italic_ (_), <em>italic</em> (em)

***str_ital*** (*), ___str_ital___ (_), <strong><em>str_ital<<em></strong> (st/em)

^13^C (^), <sup>13</sup>C (sup)

H~2~O (~), H<sub>2</sub>O (sub)

~~Not~~ (~~), <s>Not</s> (s)

<u>underline</u> (u), <ins>underline</ins> (ins)

### Introduction

Single citation is entered here
[@arifClinicallySignificantProstate2020].

### Material and Methods

Multiple citations are combined with semicolon [@arifClinicallySignificantProstate2020;
@takahashiProstateMRICharacteristics2021].

### Results

### Discussion

### Tables

Pipe method

|  Right | Left  | Default  |   Center   |
| -----: | :---- | -------- | :--------: |
| orange | apple | melon    | strawberry |
|  horse | tiger | elephant |    bear    |
|      3 | 2     | 1        |     1      |


Grid method

+--------+-------+----------+-------------+
|  Right | Left  | Default  |    Center   |
+=======:+:======+==========+:===========:+
| orange | apple | melon    | strawberry\ |
|        |       |          | blueberry   |
+--------+-------+----------+-------------+
|  horse | tiger | elephant |     bear    |
+--------+-------+----------+-------------+
|    3   | 2     | 1        |      1      |
+--------+-------+----------+-------------+

### Figures

![](figure1.jpg)

**Figure 1A** This figure shows that.

### References

library.bib

This is a .bib file exported from your Zotero library. You export it using the Better BibTeX plugin. In Zotero, select a Library or Collection, then right-click and choose Export Library (or Export Collection). If you check “keep updated,” the .bib file will automatically update when your Zotero library changes.

custom-reference.docx

This is a reference document used by Pandoc when converting to docx. Run the following commands to generate custom-reference.docx inside the Manuscript folder:

cd Documents/Manuscript

pandoc
  -o custom-reference.docx
  --print-default-data-file reference.docx

When you open custom-reference.docx in Word, you will see several items in blue. If you open the Styles panel (top right), you will see styles such as Heading 1 and Heading 2. Right-click the style you want to change and modify it. Note that editing the text in the document does not change the style—make sure you edit the style settings themselves.

fig1.jpg

This is the figure file you will insert into the manuscript. Save any figure image as fig1.jpg .

pandoc_md2docs.sh

This is the script that runs Pandoc. The first line converts input.md to output.docx . The following lines specify the bibliography file, citation style, and Word reference style. Copy the text below and save it as pandoc_md2docs.sh .

pandoc -s input.md -o output.docx
  --bibliography=library.bib
  --csl=../../../Zotero/styles/nature.csl
  --reference-doc=custom-reference.docx
  --citeproc

Also, change permissions so you can run this script from the command line:

chmod +x pandoc_md2docs.sh

nature.csl

This is the Zotero citation style file. In Zotero Preferences → Cite, you can select a citation style. nature.csl is included by default, but if you want a different style, you can search and import it. Imported styles are saved in Zotero’s Styles folder.

In this setup section, we covered installing Pandoc and Zotero and preparing the files required for conversion.

Continue to Part 2: Testing .

Last updated: November 1, 2022