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.