How to write in Markdown on Overleaf
[Post-publication note (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 light-weight 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:
Grocery list
Remember to grab as much as we can during upcoming sales!
Food
- baked beans
- spaghetti
Stationery
- writing pad
- pencils
Neat (and simple), huh? You can find other syntax for Markdown here.
Sooo what does this mean for me? I write LaTeX, and I thought Overleaf supports only LaTeX. Although that does look simple and nice.
Now many a LaTeX user is immensely contented with their beautiful LaTeX-typeset documents, but can’t help but feel a pang of envy at Markdown users—because, well, LaTeX markup can get rather verbose at times. (Yes, lists, I’m looking at you.)
Well now with the fantastic new markdown LaTeX package, you can write markdown syntax in your LaTeX documents (i.e. simpler inputs) to get beautiful output PDFs! So all you need to do is to 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 would most likely make developer-types very happy, who can now just copy their .md documentation over.)
But wait… then I can no longer use LaTeX commands if I write Markdown? Boo!
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)
Now here’s the thing: **you can’t type the # character ** when in the markdown environment. Not even \# will work. You’ll have 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 I just end the current markdown environment, write the problematic lines in ordinary LaTeX mode, and then start another markdown environment.
[Note added on 13 May, 2017] Since version 2.5, one 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!
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.
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.
[Note 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.
The usual markdown package options I use is:
\usepackage[footnotes,definitionLists,hashEnumerators,smartEllipses,hybrid]{markdown}
so that I can use the footnote markdown syntax (like [^1]); ability to use definition lists and # for numbered lists; “proper” ellipses. Here’s a complete example in the Overleaf gallery, and here’s another one.
In your 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}}
}}
[Updated 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:
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}
Does this mean we now have a way to write 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. It’s my wish item, too.
[Note 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—I may do a quick future blog post on this!
Oh well. What other things can I do with this then?
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!