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 allows 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!

Including images (updated 8 November 2022)

• Note: The next example uses a graphics file (example-image.pdf) provided by the mwe package. Those graphics files are distributed by TeX Live and thus stored on Overleaf's servers, making them available as image placeholders, such as the example below.

Images can be included in markdown by writing markup of the following format:

![alt-text](file-name "image caption")

Hopefully, the parameter names alt-text, file-name and "image caption" describe what they do. Here is an example to demonstrate them:

\documentclass{article}
\usepackage[hybrid]{markdown}
% The mwe package provides example images. Loading it is
% not essential because those images are in LaTeX's search path. 
% Here, we load it for clarity in this example.
\usepackage{mwe}
\begin{document}
\begin{markdown}
This example shows how to import a graphics file. Here we are using an
example image provided by the `mwe` package.

% Use \setkeys{Gin} if you need to change an image's display size

\setkeys{Gin}{width=.5\linewidth}
![This is alt text to describe my image.](example-image.jpg "An example image provided by the \texttt{mwe} package.")
\end{markdown}
\end{document}

 Open this example on Overleaf.

This example produces the following output:

Note on the image width

Like most packages, markdown loads other packages, including keyval and graphicx, to make use of the commands and features they provide. Here, the image width is set using the \setkeys command, which is provided by keyvals. Gin is a "family" of keys defined by the graphicx package.

• Note: Because a LaTeX command, here \setkeys, is used within the markdown environment, the hybrid option of the markdown package is required.

Changing float placement identifiers (more advanced)

The markdown syntax for figure inclusion doesn't let you directly specify the float placement identifiers, but you can adjust them by redefining how the figure is rendered:

\markdownSetup{renderers={
  image = {\begin{figure}[hbt!]
    \centering
    \includegraphics{#3}%
    \ifx\empty#4\empty\else
    \caption{#4}%
    \fi
    \end{figure}}
}}

For more information refer to the markdown documentation.

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!