How to write in Markdown on Overleaf

Post-publication update (added 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.

Huh, what?

Markdown is a lightweight markup language (get it? 😉) that lets you write up something in plain text with some very simple rules, and then transform it to formatted outputs, e.g. HTML. It's very popular among software developers and programmers, exactly because of its simplicity (and might I add, perfect for note-taking too!).

For example, to write a quick shopping list:

# Grocery list
*Remember* to grab as much as we can during upcoming [sales](http://acme-marg.com)!
## Food
- baked beans
- spaghetti
## Stationery 
- writing pad
- pencils

And you'll get as HTML output, using a tool such as pandoc:

<h1 id="grocerylist">Grocery list</h1>
<p><em>Remember</em> to grab as much as we can during upcoming <a href="http://acme-marg.com">sales</a>!</p>
<h2 id="food">Food</h2>
<ul>
<li>baked beans</li>
<li>spaghetti</li>
</ul>
<h2 id="stationery">Stationery</h2>
<ul>
<li>writing pad</li>
<li>pencils</li>
</ul>

Nice and simple! You can find other syntax for Markdown here.

So what does this mean for me?

Many LaTeX users are satisfied with their beautiful LaTeX-typeset documents, but can't help feeling a twinge of envy at Markdown users—because, well, LaTeX markup can get rather verbose at times. Yes, lists, we're looking at you...

The good news is that the fantastic new markdown LaTeX package allos you to write markdown syntax in your LaTeX documents (i.e. simpler inputs) and still get beautifully typeset PDFs! All you need to do is load the markdown package in your document, and enclose your Markdown material within a markdown environment:

\documentclass{article}
\usepackage{markdown}
\begin{document}
\begin{markdown}
# Grocery list

*Remember* to grab as much as we can during upcoming [sales](http://acme-marg.com)!

## Food

- baked beans
- spaghetti

## Stationery 

- writing pad
- pencils
\end{markdown}
\end{document}

Or if you prefer to put your Markdown material in a *.md file:

\documentclass{article}
\usepackage{markdown}
\begin{document}
\markdownInput{example.md}
\end{document}

Neat! This will most likely make developer-types very happy because they can now just copy across their .md documentation!

Can I still use LaTeX commands if I write Markdown?

Yes, you can still use LaTeX commands in your Markdown material! Just pass the hybrid option to markdown:

\usepackage[hybrid]{markdown}
...
- writing pad (the kind with the big $E=mc^2$ on the cover)

How can I use literal characters such as '#' and '_' (underscores)?

Typing a '#'

You cannot type the '#' character inside the markdown environment. Not even \# will work. You need to define a command like \newcommand{\texthash}{\#}, and then use \texthash in your markdown environment. Similarly for underscores, especially when there are more then one on the same line, e.g. $y = m_1 + n_2$. Sometimes it can be easier to end the current markdown environment and write problematic lines in ordinary LaTeX mode, and then start another markdown environment.

Typing '_' (underscore) and '`'(backtick)

Update (added on 13 May, 2017): Since markdown version 2.5 you can set underscores = false and codeSpans = false to disable underscores and backticks. This makes it possible to write math subscripts and quotation marks in hybrid mode without escaping. We have asterisks for emphasis, so the only thing truly lost are inline code examples. Thanks Vít for the tip!

Environments to avoid...

And while you can use backticks to write inline-verbatim, or indent the line with four spaces for a verbatim block, don't use lstlisting nor minted LaTeX environments within markdown environments. Just don't.

Using HTML in a markdown environment

And no, you can’t use HTML inside the LaTeX markdown environment (even though this is a common thing to do in usual Markdown). Sorry.

Update (added on 13 May, 2017): As of markdown v2.3, there's an html option that will not display HTML tags verbatim if they're present in your markdown material, though it won't actually format the tag contents either—i.e. <strong>Hello!</strong> will just display Hello! in normal weight. But HTML entities like © will be rendered as ©. Thanks to Vít for pointing this out.

Suggested markdown package options

One set of markdown package options you may find useful is:

\usepackage[footnotes,definitionLists,hashEnumerators,smartEllipses,hybrid]{markdown}

Those options enable the use of

• footnote markdown syntax (like [^1]);
• definition lists and # for numbered lists;
• "proper" ellipses (…).

Here's a complete example in the Overleaf gallery, and here's another one.

Hyperlinks and footnotes: how?

In the Overleaf example the hyperlink is a footnote. How do I get it to be a hyperref-hyperlink?

markdown is customisable, so you can define how you'd like different elements to be rendered. Adding these to your preamble will do exactly that:

\markdownSetup{renderers={
  link = {\href{#2}{#1}}
}}

Update (added 13 May, 2017): rendererPrototypes was used in the initial version. Normal users are recommended to use renderers for their own definitions, as rendererPrototypes is there for package creators to provide defaults. If you modify rendererPrototypes, you run the risk that another package may override your settings. Thanks to Vít for pointing this out!

What about figures and cross-references?

The following will create a captioned figure and a cross-reference to it:

![exampleimage](example-image.jpg "An exemple image")
Cross referencing: Figure~\ref{fig:exampleimage}

Note that you need to add the fig: prefix in the \ref. Also, this syntax doesn't let you specify the float placement identifiers nor the \includegraphics width and height. You could define/change how the figure is rendered:

\setkeys{Gin}{width=\linewidth}
\markdownSetup{renderers={
  image = {\begin{figure}[hbt!]
    \centering
    \includegraphics{#3}%
    \ifx\empty#4\empty\else
    \caption{#4}%
    \fi
    \label{fig:#1}%
    \end{figure}}
}}

That way if you'd like to change the width of an image, you could write

\setkeys{Gin}{width=7cm}
![exampleimage](example-image.jpg "An example image")

Can you create tables using markdown in LaTeX? 😀

Unfortunately, no. Tables are supported in MultiMarkdown only, and the LaTeX markdown package has no support for it at present.

Update (added on 13 May, 2017): Based on a tip from Vít, it's possible to use the contentBlocks syntax extension since version 2.4, or tweak the inputFencedCode renderer, to quickly turn some CSV-style text to a table.

More markdown package goodies...?

As mentioned earlier, it's a cool way for note-taking, and when combined with some nice LaTeX document classes or package setups, lets you have a beautiful notebook at the end of a lecture itself. For example, you could use it with the Tufte classes:

\documentclass{tufte-handout}
\usepackage[footnotes,definitionLists,hashEnumerators,smartEllipses, hybrid]{markdown}
\begin{document}
\markdownInput{PHY303-lecture-12Nov2016.md}
\end{document}

And the short-and-simple syntax that makes writing lists much more convenient means we now have a really quick way of writing Beamer presentations and posters!

Have fun!