# Write scientific paper in markdown

## Introduction

If you have ever written a scientific paper in MS Word (or any other word processing software) then you’re probably experienced frustrations like me: Word constantly crashing when loaded with too many high-resolution figures, citations getting messed up when working with others that use different citation managers, or hard to keep track of hundreds of versions of the draft, etc.

Of course, Latex is always an excellent solution to all those problems. It separates content and formatting, allowing you to focus on content and leave the rest to those with expertise at it. A Tex file is also a pure text format so it’s easy to manage with a version control tool like git. However, Latex does have a rather steep learning curve. And a Tex file is not the most intuitive format to look at. For example, look at the below Tex format:

Another problem with writing in Latex is, while it’s not easy to learn Latex, it’s even harder to get all your collaborators on board, which is usually the case with scientific papers.

That led me to think: markdown is a fantastic format that is both intuitive and powerful. Why not write in markdown? After a short search, I’m happy to report that this is indeed possible!

#### What does writing a scientific paper require?

Content aside, to write a scientific paper efficiently, one needs at least the following elements:

    Easy way to insert and manage citations.
    Easy way to insert and manage high resolution figures
    Easy way to format tables
    Can be converted to other formats (pdf, html, etc)
    Allows collaborative writing

Atom is an excellent text editor that with packages can do almost all of the above!
#### Required software and packages

Atom
markdown-preview-enhanced
zotero-citations

Pandoc

A Tex distribution for your OS (I used Tex Live for my linux system)

Zotero citation manager
Bbibtex Add-on

Once you have all required packages installed, it’s time to start writing!

#### Write a paper

Writing a paper in markdown is as easy as it sounds: use # for titles and subtitles, use | to format a table, among other things.

#### Write math equations

You can use Latex syntax to write a math equation, like so:

$f_A^2+2f_Af_B+f_B^2=1$

f2A+2fAfB+f2B=1

#### Import figures:

You can insert a figure in typical markdown way:

![alt text](figure.png)

This would import the figure at current location. You can even further configure the figure like so:

![alt tex](figure.png){#id .class width=300px height=200px}

Note: Because markdown preview enhanced by default uses a different render engine to render the preview, you will not see change to figure size in the preview but it will be rendered when converting to another output. You can also change its default markdown render engine to pandoc to see size change in preview.

#### Insert citations:

In order to insert a citation, you need to have zotero open. With zotero open, you can call up zotero citation picker by either pressing ctrl + alt + P or pressing ctrl + shift + P to call up the command palate and search for “zotero citations: pick”. In the citation picker window like below:

type in the reference you wish to insert and hit enter. A string of citation key should appear in your document:

@bryoisEvaluationChromatinAccessibility2018

Surround this reference key with [] and you’re good to go! Once you export this document to a pdf, word, or html format, the reference will be automatically appended to the end of your document and the ref key will be replaced with corresponding references, like so:

To add multiple citations, use ; to separate ref keys, like so:

[@bintuSuperresolutionChromatinTracing2018; @bryoisEvaluationChromatinAccessibility2018]

Lastly, in order for pandoc to render citations correctly, you must provide a bib file that contains all your citations and their corresponding ref keys.

To do this, head on to zotero and click File -> Export library, in the format section, choose Better Bibtex. If you want the exported library up to date with your zotero library, check Keep updated. Once you have the exported library, add yaml frontmatter to the beginning of your document, like so:

---
bibliography: My Library.bib
---

#### Export to other formats

With pandoc, you can easily convert the markdown format to other text formats like pdf, word, and tex. To do this, first add output: word_document to your document’s frontmatter, like so:

---
bibliography: My Library.bib
output: word_document
---

and then you can right clock on the preview panel on the right to export the document through pandoc: This will output your document to a Word document. To output to PDF, simple change the value of output in frontmatter to pdf_document.
#### Conclusion

Markdown is an incredibly intuitive text format and yet still versatile and powerful enough for productive writing. It has recently surged to new favorite of many among developers, scientists, and journalists. It will certainly keep raising in popularity due to its friendliness and expandability.

Adapted from: https://www.sichong.site/2019/08/07/write-scientific-paper-in-markdown/

## How to make Mendeley work nicely with Markdown

### Step 1:

First and foremost, Mendeley’s library isn’t fit for direct citations in your document. You have to go to preferences and enable sync to BibTeX library, like so:
The box “Enable BibTex syncing” must be ticked

Every time you add something to your library in Mendeley, it will be synced to a .bib file. I recommend putting this file in the same folder as the markdown document. I keep everything on my desktop, that’s the most straightforword solution for what’s coming next.

### Step 2:

Install LaTeX. Go to:

https://miktex.org/

and use the minimal installer to provide your computer with basic LaTeX framework. You’ll see what’s that for in a while.

### Step 3:

Install pandoc. Pandoc is a free terminal-level or command-line-level app that will basically allow you to convert the Markdown file to many MANY different formats including .tex, .pdf, .html and .docx as well.

Go to http://pandoc.org/, download the package and install it. Don’t run the program just yet.

Tip: if you use a Mac and have homebrew package manager installed, run a command brew install pandoc in the terminal. It will download and install pandoc right away.

### Step 4:

Type some sample text for your thesis with a sample citation from your library in a Markdown editor of your choice.

If you’re not sure what app to use, skip for a while to the section “How to type in Markdown efficiently” of this article and pick something of your liking. For starters I recommend MacDown if you’re working on Mac. For people with coding experience Atom will be a no-brainer.

The document should look sort of like this:

---
title: "Romeo and Juliet"
subtitle: "A teenage drama"
author: William Shakespeare
---Romeo kills himself because Juliet pretended to be dead. [@Shakespeare1591]

The top part surrounded by triple dashes is the YAML header. Always include that header. The acronym translates to Yet Another Markup Language and is a simple markup language used by pandoc to create certain elements necessary in LaTeX but generally not present in native Markdown files. It looks sort of like this:

---
title: "Romeo and Juliet"
subtitle: "A teenage drama"
author: William Shakespeare
csl: "/Users/user/Documents/vancouver-superscript.csl"
header-includes:
  - \usepackage{color}
  - \usepackage{caption}
  - \usepackage{anysize}
---

Title, subtitle, author speak for itself. CSL is a file containing citation rules. header-includes can be used to pass certain LaTeX commands to pandoc and pandoc will put them in the document preamble. This is useful when you later want to use some specific LaTeX packages. Pandoc accepts some other parameters from YAML as well. These are the most basic ones and most used ones, so if you really need to know more, head to pandoc documentation, here:

https://pandoc.org/MANUAL.html

If this overwhelms you, leave it be, use the standard header.

Next thing: how do you cite? Well, the answer is hidden in the Romeo and Juliet example above. If you go to any article in Mendeley, in the citation box on the right you will be able to see something called citation key if you scroll down a bit. Basically every time you want to cite an article, write in your Markdown document [@AuthorYYYY].
You can see the citation key on the right

Citation keys consist usually of lead author surname and the year the work was published. Just put it in square brackets and prepend with ‘@’ symbol as if you were tagging someone on Twitter.

### Step 5:

Now the magic happens. Go to the Terminal and get to the directory where you have your .bib and .md file. In Mac terminal you simply use cd command to get there.

Let’s say I want to get to /Users/user/Desktop/MyArticle. I type into the terminal: cd /Users/user/Desktop/MyArticle and I’m in the right folder. Remember I said I keep all of these stuff on my desktop? That’s because Terminal usually starts in the directory /Users/user and you can simply type cd Desktop to get to /Users/user/Desktop/ from there.

Now type in the following command:

pandoc -s article.md --bibliography library.bib -o article.pdf

-s specifies the input file, --bibliography library.bib specifies your BibTeX library file you created with Mendeley, -o specifies output filename and format
### Step 6:

Go to the folder you had your .md file in. You should now see a .pdf file. Open it and check if the document rendered properly, especially citations. If yes, you can now keep on typing your thing and inserting as many citations as you want. Each time you finish a chunk of the text and want to look at the PDF, just run the command from step 4 again (tap ‘up’ arrow on your keyboard while in Terminal and then return).
Step 7: (optional)

You can run the command from step 4 changing the format from article.pdf to article.tex and this will produce a LaTeX file you can later modify to your liking.

## Writing thesis in markdown
### You won't scape Latex

You may write your thesis in Markdown and then use pandoc to render the thing but there are always certain formalities involved. For example I had to include a particular type of a title page and no matter how much I tried to pull it off through pandoc, it just never looked good enough! Besides, anytime you include graphics the text may wrap eerily on the page and you will be hard-pressed to fix it. But it will only work with LaTeX.

### Advanced formatting may not be possible in Markdown

GitHub flavored Markdown relies on HTML syntax to extend the formatting options. You can use pandoc to convert it to HTML file and I use it on a regular basis now, however basically any other file format is brought down to LaTeX syntax and generally the HTML elements are ignored. So things like boxes with background under the text are out of the question at least when you’re counting on HTML elements.

### You have to provide an appropriate CSL file to change citation formatting

This is simple, as all you have to do is basically download a file with the style you want, you can even modify the file if you know how to and create your own citation style if your university has some weird rules about it.

But on the other hand it’s yet another file. And you will have to include this in the header.

### Table of contents may prove problematic

Table of contents can be rendered automatically from your document if you include --toc option in the pandoc command you put into the Terminal. But maintaining it when your supervisor wants you to keep numbering for these sections but introduce bullet lists for the other sections or bold out names of all chapters excluding this particular one, things quickly become messy and LaTeX comes in handy once again.

### You have to be prepared for a lot of tweaking

When writing any paper, your supervisors will request many revisions and corrections. Sometimes formatting changes that would be possible in MS Word, are not so trivial when using this framework. I made this easier for myself by splitting the paper into chapters, saving each chapter as a separate file and discussing it with my superiors.

Adapted from: https://medium.com/@krzysztofczarnecki/i-wrote-my-thesis-in-markdown-heres-how-it-went-3f60140dfe65

## Creating Documents
### Structure

The example documents in Markdown Templates are structured as follows:

<name>/
├─ build/
├─ <filename>.md
├─ bibliography.bib
└─ Makefile

The Markdown file <filename>.md is where we write the content of the document. We use the bibliography.bib file to store bibliographical entries in BibTeX format, which we can refer to in the Markdown document.

The Makefile contains commands for converting the Markdown file into the desired document format using Pandoc. Pandoc creates the output files to the build/ directory, which Makefile automatically creates if it does not exist.

Makefile
Common

We define the build directory and the filename at the beginning of Makefile as follows.

BUILDDIR=build
FILENAME=<filename>

Then, we define the command to create the document.

<command>:
    mkdir $(BUILDDIR) -p  # Creates the BUILDDIR if it doesn't already exist.
    pandoc $(FILENAME).md \
    --filter pandoc-citeproc \
    --from=markdown+tex_math_single_backslash+tex_math_dollars \
    # ...

The option --from=markdown tells that input file is a Markdown file. Markdown extensions +tex_math_single_backslash and +tex_math_dollars enable Pandoc to parse equations.

Pandoc-citeproc enables us to use citations in Markdown. Pandoc installation includes it by default. We need to enable it by using the option --filter pandoc-citeproc.

We can execute the Makefile command in the terminal as follows.

make <command>

Next, we define concrete examples of Makefile for creating PDF, HTML, and EPUB documents.

#### PDF

pdf:
    mkdir $(BUILDDIR) -p  # Creates the BUILDDIR if it doesn't already exist.
    pandoc $(FILENAME).md \
    --filter pandoc-citeproc \
    --from=markdown+tex_math_single_backslash+tex_math_dollars+raw_tex \
    --to=latex \
    --output=$(BUILDDIR)/$(FILENAME).pdf \
    --pdf-engine=xelatex

Markdown extension +raw_tex enables us to insert raw LaTeX inside the Markdown document, and the --pdf-engine=xelatex option enables us to use Unicode characters within the Markdown document.

#### HTML

html:
    mkdir $(BUILDDIR) -p  # Creates the BUILDDIR if it doesn't already exist.
    pandoc $(FILENAME).md \
    --filter pandoc-citeproc \
    --from=markdown+tex_math_single_backslash+tex_math_dollars \
    --to=html5 \
    --output=$(BUILDDIR)/$(FILENAME).html \
    --mathjax \
    --self-contained

The --mathjax flag enables math rendering for HTML via Mathjax, and the --self-contained flag includes style sheets to the output document.
#### EPUB

epub:
    mkdir $(BUILDDIR) -p  # Creates the BUILDDIR if it doesn't already exist.
    pandoc $(FILENAME).md \
    --filter pandoc-citeproc \
    --from=markdown+tex_math_single_backslash+tex_math_dollars \
    --to=epub \
    --output=$(BUILDDIR)/$(FILENAME).epub \
    --epub-cover-image=<cover-image> \
    --toc

For e-books, we need to enable the table of contents needs using --toc flag. We can also include a cover image of size 1600 x 2400 pixels in JPG or PNG formats using --epub-cover-image=<cover-image> option.
Front Matter

We can include document-specific metadata and functionality for the converter in the Front Matter at the top of a <filename>.md file. We write the front matter in YAML between two triple-minus lines --- as follows.

---
title: "Title"
date: \today
author: "Author"
bibliography: "bibliography.bib"
link-citations: true
urlcolor: "blue"
csl: "https://raw.githubusercontent.com/citation-style-language/styles/master/harvard-anglia-ruskin-university.csl"
---

The title, date, and author variables specify information for creating the title. The bibliography variable specifies the location of the bibliography file, link-citations toggles links to citations on and off, urlcolor defines the link color, and the csl variable defines the Citation Style Language. We can find examples of citation styles from Zotero styles and use them by either downloading them or referring directly to the URL of the raw CLS file in citation styles repository.
Layout

We can change the layout of a PDF document by including a LaTeX preamble using a Pandoc command or the Front matter. For example, if we want to create an ebook friendly PDF output, we can use the layout described in “Effort to make latex ebook friendly” as follows.

We can include --include-in-header=<layout>.tex option in the Makefile with <layout>.tex file:

\usepackage[papersize={4.5in,6in},margin=0.5cm]{geometry}
\setlength{\parskip}{2pt}
\newcommand\textbreak{%
  \begin{center}%
  \decothreeleft \aldineleft \decosix \aldineright \decothreeright%
  \end{center}}
\pagestyle{empty}

Alternatively, we can include the header-includes variable in the front matter:

header-includes: |
    \usepackage[papersize={4.5in,6in},margin=0.5cm]{geometry}
    \setlength{\parskip}{2pt}
    \newcommand\textbreak{%
    \begin{center}%
    \decothreeleft \aldineleft \decosix \aldineright \decothreeright%
    \end{center}}
    \pagestyle{empty}

Adapted from: https://jaantollander.com/post/scientific-writing-with-markdown/

## Other resources

1. https://blog.kdheepak.com/writing-papers-with-markdown.html