Markdown and LaTeX

Intro

Markdown is an easy-to-use plain text formatting syntax. More importantly, markdown documents are easy to read. They're meant not to look like they've been marked up with tags or formatting instructions.

I write my class notes in markdown (.md file extension). I'm able to format text, add code blocks, insert links, and more. In some cases, I need to add mathematical expressions. Rather than write the entire document in LaTeX, which is great for typesetting math, but not so great for readability, I only use it as needed within my .md files. While markdown doesn't natively support LaTeX, pandoc, "a universal document converter," does. pandoc makes converting to other file formats easy, too.

In this post, I'll go through some markdown examples. And show how to convert .md files with embedded LaTeX to PDFs.

Markdown

There are several implementations of markdown. For our purposes, we'll focus on GitHub Flavored Markdown. The syntax is fairly straight forward.

Document headings denote sections and subsections. In markdown, headings start with a hash symbol (#). If you're familiar with heading tags in HTML, you'll see the parallel. Single hash symbols correspond to a first level headings, two correspond to second level headings, and so on.

To emphasize (italicize) words—one or many—use single asterisks at the beginning and end. For example, *yes* becomes yes. For important text (bold), use double asterisks.

You can create unordered lists by using either * or - characters before each element and putting each element on its own line. Ordered lists follow the same format, but use numbers followed by periods.

Backticks (`) are used for code. Inline code uses single backticks. For a code block, use triple backticks at the beginning and end of your code. For example,

```
import numpy as np
np.random.randint(2, size=10)
```

becomes

import numpy as np
np.random.randint(2, size=10)

With markdown, you can even create tables using dashes and pipes. For more information on that, see this.

To insert links, use both square brackets and parentheses—square brackets around the text to be linked and parentheses around the URL. For example, [text](url).

LaTex

LaTeX is a typesetting system that is used in the publication of technical and scientific documents. There are two modes for inserting mathematical expressions using LaTeX—inline and display. This is similar to the two ways to use markdown for code.

For inline mode, you can either use $...$ or \(...\). As an example, \(E = mc^2\) yields \(E = mc^2\). Alternatively, \begin{math} and \end{math} can be used.

To insert display-mode expressions, use double dollar signs or square brackets—e.g., \[...]\.

For installation on OS X, I recommend installing the smaller, BasicTeX distribution. Find the .pkg file here.

Pandoc

pandoc supports converting files in 14 different formats, including markdown, HTML, and LaTeX, to several others. For OS X, you can download and install the .pkg file here.

Converting

Once you have your markdown file with embedded LaTeX, converting is simple. At the command line, navigate to the directory that contains your input file—that is, the .md file you want converted. Then, run the following.

$ pandoc -o <outfile>.pdf <infile>.md

Mathematical expressions with high-quality typography achieved!

Final Thoughts

With pandoc, you can add additional functionality to your markdown files. Directly insert mathematical expressions using LaTeX's syntax into your document. Then, use pandoc to render the formatted text and output a PDF.

Special thanks to Matthew Lewis for his excellent post on the subject.