Reach for Markdown, not LaTeX

February 26, 2017

I’ve written in the past (twice) about how to streamline the writing process when using LaTeX. Since then, I’ve found that I enjoy writing even more when I don’t have to reach for LaTeX at all. By reaching first for Markdown, then for LaTeX when necessary, writing is easier and more enjoyable.

Writing at the Command Line

Last year, I gave a talk about the merits of writing primarily at the command line. My main claims were that when writing we want:

  • an open document format (so that our writings are future proof)
  • to be using open source software (for considerations of privacy and cost)
  • to optimize for the “common case”
  • to be able to write for print and digital (PDFs, web pages, etc.)

Markdown solves these constraints nicely:

  • It’s a plain text format—plain text has been around for decades and will be for decades more.
  • Given a plain text format, we can bring our own text editor.
  • Plenty of open source programs manipulate Markdown.
  • When we need advanced features, we can mix LaTeX into our Markdown documents.

For those unfamiliar with Markdown, it’s super quick to pick up. If you only look at one guide, see this one:

If you want to start comparing features available in certain implementations of Markdown:

For more on why you should want to be writing at the command line, you can check out the talk slides.

Pandoc Starter

The central tool I spoke about in Writing at the Command Line is Pandoc. Pandoc is an amazingly simple command line program that takes in Markdown files and spits out really anything you can think of.

To make using Pandoc even easier than it already is, I put together a collection of starter templates. They’re all available on Github if you’d prefer to dive right in.

There are currently six different templates, specialized for the kind of document you’d like to create. Each has a README for installation and usage instructions, as well as a Makefile for invoking pandoc correctly.

All the templates generate PDFs from Markdown by way of LaTeX. In addition to Pandoc, you’ll also need LaTeX installed locally.


This template uses the standard LaTeX article document class. It’s a no frills, no nonsense choice.

article template


As an alternative to the article document class, there’s also the tufte-handout document class. It originates from the style Edward Tufte popularized in his books and articles on visualization and design.

Apart from a different font (it uses Palatino instead of the default Computer Modern), this template features the ability add side notes to your documents. I often find myself reaching for this template when I want to disguise the fact that I’m secretly using LaTeX.

tufte-handout template


A second alternative to the article document class is the homework document class. It works nicely for homework assignments and problem sets. The class itself has a number of handy features, like:

  • the option to put your name on every page, or only on the first page
  • an option to use wide or narrow margins
  • most of the AMS Math packages you’d include in the process of typesetting a math assignment
  • a convenient environment for typesetting induction proofs

For more features and usage information, check out this blog post or the source on GitHub.

homework template


LaTeX provides the beamer document class for creating slides; this template makes it even easier to use:

  • Make a new slide with a “##” header
  • Make a section divider with a “#” header
  • Mix lists, links, code, and other Markdown features you’re familiar with to create the content for a slide.

So basically, just write the outline for your talk, and Pandoc takes care of making the slides—it doesn’t get much simpler.

beamer template


The default beamer styles are pretty boring. To add a bit of flair and personality to my slide decks, I made a Solarized theme for beamer.

In addition to the screenshot below, the Writing at the Command Line slides I linked to earlier also use this theme, if you want to see a less contrived example.

beamer solarized template


Finally, sometimes a simple article or slide deck doesn’t cut it. Usually this means I’d like to group the writing into chapters. This template makes writing a chapter as easy as using a “#” Markdown header.

book writeup template

Writing Plugins for Vim

If you happen to use Vim, I’d highly recommend installing goyo.vim for writing. It removes all the visual frills Vim includes to make writing code easier so you can focus on your writing without distractions.

I also really enjoy vim-pandoc and vim-pandoc-syntax. They’re a pair of complementary plugins for highlighting and working with Pandoc Markdown-flavored documents. They work so well that I use them for Markdown documents even when not using Pandoc.

Reach for Markdown

Writing should be a pleasant experience. With the right tools, it can be. LaTeX is powerful but cumbersome to use. With Markdown, we can focus on our writing, and worry about the presentation later. Pandoc can take care of the presentation for us, so the only thing left to do is start.

Jake on the Web

If you cared enough to read that far, you should consider following me on GitHub or paying a visit to my homepage. If this post was about one of my open source projects, make sure to star it on GitHub! I love hearing what people think, so feel free to comment, open an issue, or send me an email.

Vim and Haskell in 2016 on OS X

Stephen Diehl’s article “Vim and Haskell in 2016” does a great job of outlining the quickest way to get a quality Haskell development experience. His post presumes Ubuntu; here we presume OS X. Continue reading

Let’s Have a Chat about Encryption

Published on April 17, 2016

SML Dev Setup

Published on March 09, 2016