Scientific Writing with Markdown

Table of Contents

Introduction

This blog post covers how to use Markdown for scientific and technical writing, which often involves writing equations, code blocks, citations, and other unique features depending on the document in question. We have included software recommendations for writing and converting Markdown it into other formats such as HTML (blog posts, slides, documentation), PDF (essays, reports) or EPUB (books). For example, I wrote this blog post using Markdown.

Markdown Basics

Markdown is a lightweight markup language with plain text formatting syntax, created for creating web content such as emails and blog posts (HTML), but can be converted into other formats such as PDF via tools like Pandoc. I use Markdown due to its popularity, simple syntax, and availability of tools that can convert Markdown into other formats.

Unlike word or google docs, Markdown is written in a plain text document and then converted into the final format. Markdown is not the best choice for documents that require lots of small customizations in styles, fonts, or outlook. For example, it is easier to writen a resume using Google docs because the customizations with colors, indentations, and fonts would be a real hassle using Markdown. On the other hand, Markdown excels at creating documents that need little customization or have premade styles available such as reports. Markdown is also among the easiest ways to create web content.

Creating Documents

We can use Markdown for writing many different types of documents. The most common use case is to write web content such as blog posts, but writing essays, research papers, books, documentation, slides, among many other types are possible. I made GitHub repository Markdown Templates that contains example documents. The examples are structured as follows:

  • <filename>.md is the source file written in Markdown.
  • <filename>.bib is the optional file for bibliography entries.
  • Makefile contains the commands to compile the Markdown documents into the desired format.

The following sections cover the required software and the basics of Markdown syntax.

Software for Markdown

To get started writing Markdown on desktop, we need to download software for writing and converting Markdown into documents.

  1. Install Pandoc. Pandoc is the primary tool that we are going to use for converting markup formats into other formats.
  2. Install LaTeX. LaTeX is a typesetting system designed for the production of technical and scientific documentation. We require LaTeX installation for creating PDF documents.
  3. Install Atom. Atom is a modern, cross-platform code editor built using web technologies. The use of web-technologies allows Atom to be extensible, customizable, and it enables other useful features. This guide heavily relies on the packages that are available to the Atom editor. Install following packages for writing Markdown by navigating to Edit > Preferences > Packages
    • language-markdown for better Markdown syntax support compared to the default package language-gfm (GitHub-flavored Markdown).
    • markdown-preview-plus package allow Markdown preview using Pandoc, which support equations and citations. You need to disable markdown-preview for this package to work correctly.
    • platformio-ide-terminal for a terminal inside Atom. We use the terminal for invoking the command for converting Markdown files using Pandoc.
    • pdf-view can be used for viewing PDF documents converting Markdown to pdf.

For writing Markdown online, for example, edit Markdown file inside Google Drive can try StackEdit, or for emails, there is browser plugin called Markdown Here.

Markdown Syntax

This section covers the basic syntax of Markdown and specific features for scientific writing such as syntax highlighting, equations, and citations.

Basics

Demonstrations about the basic Markdown syntax can be found from John Gruber’s original spec or Markdown Cheatsheet in GitHub. I recommend reading at least Markdown-Cheatsheet to understand the basics. In addition to Markdown understanding, basics on HTML can be useful for creating web content if using inline HTML.

Syntax Highlighting

Regular Markdown syntax supports code blocks but not syntax highlighting. Support for syntax highlighting can be achieved through the use of converters such as Pandoc that supports it as well as sites such as GitHub supports it by default.

def foo():
    return "bar"

Equations

Equations can be written either using \[ ... \] or inline using \( ... \). For example, Cauchy’s integral formula can be written as

\[ f(a)={\frac {1}{2\pi i}}\oint _{\gamma }{\frac {f(z)}{z-a}}\,dz \]

which in HTML will be displayed by Mathjax as

$$ f(a)={\frac {1}{2\pi i}}\oint _{\gamma }{\frac {f(z)}{z-a}},dz $$

Inline equations such as $a^2 + b^2 = c^2$ which in Markdown translates to \(a^2 + b^2 = c^2\) will display on the same line as the text. In order for this to work in HTML, we need to use Pandoc option --mathjax.

Another feature that can make writing complicated equations easier is using unicode characters for mathematical symbols. For instance \[ 𝐱 ∈ ℝ^2 \] can be rendered by Mathjax

$$ 𝐱 ∈ ℝ^2 $$

In order to easily input these mathematical symbols install Atom package latex-completions. A mapping between corresponding Unicode characters and latex commands can be found at unimathsymbols.txt.

Citations

Citations can be used inside Markdown by using pandoc-citeproc library, which included in the Pandoc installation. To use pandoc-citeproc Pandoc needs to be invoked using options.

  1. --filter pandoc-citeproc and
  2. --bibliography=FILE to include the given bibliography file.

Bibliography entries are stored in a bibliography file <filename>.bib using biblatex syntax. For example, articles are stored using @article

@article{key_article,
    author  = {Peter Adams},
    title   = {The title of the work},
    journal = {The name of the journal},
    year    = {1993},
    number  = {2},
    pages   = {201-213},
    month   = {7},
    note    = {An optional note},
    volume  = {4}
}

Online resources such as websites are stored using @online

@online{key_online,
    title        = {Generating Bibliographies with biblatex and biber},
    organization = {Wikibooks},
    date         = {2016},
    urldate      = {2016-03-07},
    url          = {https://en.wikibooks.org/wiki/LaTeX/Generating_Bibliographies_with_biblatex_and_biber},
    keywords     = {untrusted},
}

These entries can be referred to using @key_name. The full Biblatex reference documentation can be found from biblatex.pdf.

Optionally citation styles can be changed using the option --cls=FILE. Citation files use Citation Style Language (CSL). Different citation styles and examples of them can be found from Zotero Styles. In order to use these styles, you can either download them or refer directly to the raw CLS file in Citation Styles (GitHub).

Jaan Tollander de Balsch
Jaan Tollander de Balsch
Student & Researcher

Jaan Tollander de Balsch is a computer scientist with a background in applied mathematics.

comments powered by Disqus

Related