Jaan Tollander de Balsch

Computer Science & Applied Mathematics

Scientific Writing with Markdown

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. I include software recommendations for writing and converting markdown it into other formats such as HTML (blog posts, slides, documentation, etc), PDF (essays, reports, etc) or EPUB (books). In fact, this blog post itself is created from a markdown file.

What is Markdown and should I use it?

Markdown is a lightweight markup language with plain text formatting syntax. It was originally made 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 document. Markdown is not the best choice for documents which require lots of small customizations in styles, fonts or outlook. For example, the resume seen on my blog is written 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 which need little customization or have premade styles available such as reports. Markdown is also among the easiest ways to create web content.

Creating Documents

Markdown can be used for writing many different types of documents. The most common use case is to write web content such blog posts but writing essays, research papers, books, documentation, slides among many other types is 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.

Next 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. LaTeX installation is required for creating PDF documents since they are created via LaTeX.
  3. Install Atom. Atom is 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 Atom. 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 properly.
    • platformio-ide-terminal for a terminal inside Atom. The terminal is used for invoking command for converting markdown files using Pandoc.
    • pdf-view for 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

Standard 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 site such as GitHub supports it by default.

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

Online resources such as websites are stored using @online

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

Optionally citation styles can be changed using 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).

Comments