Markdown into LaTeX with Style

Post-publication update (13 May, 2017): We are grateful to Vít Novotný, the author/maintainer of the markdown package, for writing to us with some helpful feedback concerning the original article. We are pleased to publish this updated version which takes note of, and includes, his advice and suggestions.

Introduction

A while ago we rejoiced at the release of the markdown package which made it possible to write markdown syntax in LaTeX documents—and celebrated it with an article called How to write in Markdown on Overleaf whose purpose was to demonstrate some of the supported syntax.

Remember: You'll need to compile your .tex files with the --shell-escape option to make it work on local LaTeX installations—Overleaf does this for you (automatically). Bear in mind that most journal-submission portals do not enable --shell-escape—unless you're allowed to upload only the output PDF of your manuscript, your LaTeX files containing markdown may not compile successfully when processed by the publisher's submission system.

One of the ideas hinted at in the earlier article is that a combination of markdown and LaTeX permits a wonderful separation of content and style. Authors (especially those already familiar with markdown) would have a much more succinct syntax to work with (with some caveats) while still having access to all the glories of LaTeX packages and templates to take care of the styling and formatting. That earlier article gave some examples of using markdown in Beamer presentations and posters: today we're going to look at even more fun and exciting styling possibilities!

Using markdown in styled LaTeX templates

Apart from the examples above, you can use use markdown in almost all templates. Here are a few quick examples:

• The Legrange orange book template
• The Tufte-inspired handout template
• This very nice article template by Thiago

You may notice that two of these are article templates and one is a book template. The markdown package detects whether the \chapter command is available for use in a particular LaTeX document and will make the first-level heading markdown line render to \chapter or \section as appropriate.

Really quick handouts: markdown + pocketmod

From the time I first learned about markdown it struck me as a quick and convenient way to take notes: it reflects how I might be scribbling down notes on scraps of paper or post-it notes—especially with the bulleted and numbered list syntax. When I first created the PocketMod template in 2015, I yearned for a way to write markdown in LaTeX so that I could create PocketMods with markdown because it felt… appropriate. Jotting down notes in a simple syntax on little folded booklets, but with nice typography—some people refer to PocketMods as "zines" because they're little 8-page booklets that you can make out of a single sheet of A4 paper.

And so indeed it was possible! This makes it rather easy to quickly produce a weekly planner mini-booklet or a little picture story book. Yes, it kept my daughter amused to see a story book made out of her own drawings… well, for all of 10 minutes! The markdown package lets you customize how each markdown syntax is rendered into LaTeX, so I redefined the standard ![](img_file "caption") syntax to put the caption under the image file (without any "Figure" prefix or numbering), and then inserted a page break. This makes it even easier to make the picture book. Here's a video showing how to fold the booklet:

Simple recipe booklets

When you think about it, a recipe is made up of lists: a list of ingredients, a list of preparation or cooking instructions, and perhaps a list of notes (cooking time, servings etc). So rather than writing this:

\begin{enumerate}
\item First do this
\item Then do that
...
\end{enumerate}

I'd certainly appreciate being able to write this:

#. First do this
#. Then do that

And similarly for the ingredients:

- 2 eggs
- pinch of salt

So, to easily produce a quick recipe we can write this:

# Scrambled Eggs

Cooking time
: 5 minutes

Serves
: 1

## Ingredients
- 4 eggs
- 1 tsp butter
- 1/4 cup milk
- salt, pepper (to taste)

## Instructions

#. Beat eggs, milk...
#. Heat butter in pan...
#. ...

Hmm, that looks promising. A few of us at Overleaf (and our families) contributed our favourite quick recipes (ideal for first-time cooks) and I whipped-up (pardon the pun) a quick recipe template that you can write with markdown and make into a mini-booklet.

Now comes another bit of fun. Under the hood this is still LaTeX so we can continue to style the various elements—sectional headings, bullet lists, fonts and so forth—using the usual LaTeX bag of tricks. This was when I got rather carried away and came up with three "themes" for the simple-recipe class!

Bonus 1: Some caveats when using the markdown package

• SyncTeX won't quite work. On Overleaf, this means the "position in preview" and "click-in-preview-to-jump-to-source" operations won't work in the markdown regions.
• \\ loses its normal meaning: the usual "two-spaces followed by a new line" markdown trick doesn't work here because trailing spaces will be removed by the Lua parser, as documented in the markdown package documentation. \newline will work, though.
• Be careful of multiple underscore characters on the same line—this can be a problem if:
  • you're working with a lot of subscripts in your equations (tip: break out of the markdown environment in such cases);
  • you like to use underscores in your BibTeX keys.

  You can set underscores=false with the latest markdown package files to make subscript underscores work, but it still won't work with underscores in BibTeX keys.

  Update (13 May, 2017): Underscores in BibTeX keys will work with markdown v2.5.2 onwards—thanks Vít!

• You'll have some difficulties displaying a literal hash character because not even \# will work! I usually define a new command and use that instead.

Bonus 2: New features in the updated markdown package

markdown v2.4 and later added support for some really nice syntax:

• Inlined footnote syntax: ...^[this is the footnote] (requires the inlineFootnotes option)
• Citations:[@smith1990] (requires the citations option; also beware of underscores in your BibTeX keys!)
• Fenced code: You can use either tildes ~ or backticks ` as the fence.

~~~~
int main() {
  cout << "Hello world!";
  return 0;
}

~~~~

If you'd like to use these new features, be sure to upload updated versions of markdown.lua, markdown.tex and markdown.sty to your project—or you can just create a new project from this template.