> For the complete documentation index, see [llms.txt](https://overleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://overleaf-pro.ayaka.space/latex/in-depth-articles/30-how-to-write-in-markdown-on-overleaf.md).
# 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](https://kirkstrobeck.github.io/whatismarkdown.com/) 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](http://pandoc.org/):
```html
Grocery list
Remember to grab as much as we can during upcoming sales!
Food
Stationery
```
Nice and simple! You can find other syntax for Markdown [here](https://daringfireball.net/projects/markdown/syntax).
### 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](https://ctan.org/pkg/markdown) 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:
```latex
\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:
```latex
\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`:
```latex
\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. `Hello!` 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:
```latex
\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](https://www.overleaf.com/latex/examples/using-markdown-in-latex-documents/whdrnpcpnwrm) in the Overleaf gallery, and here's [another one](https://www.overleaf.com/articles/how-to-write-using-rich-text-format-and-markdown-in-latex-and-overleaf/dbqrxvftzskw).
### 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:
```latex
\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:
```latex
```
Hopefully, the parameter names `alt-text`, `file-name` and `"image caption"` describe what they do. Here is an example to demonstrate them:
```latex
\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}
\end{markdown}
\end{document}
```
[Open this example on Overleaf.](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Using+images+in+markdown\&snip=%5Cdocumentclass%7Barticle%7D%0A%5Cusepackage%5Bhybrid%5D%7Bmarkdown%7D%0A%25+The+mwe+package+provides+example+images.+Loading+it+is%0A%25+not+essential+because+those+images+are+in+LaTeX%27s+search+path.+%0A%25+Here%2C+we+load+it+for+clarity+in+this+example.%0A%5Cusepackage%7Bmwe%7D%0A%5Cbegin%7Bdocument%7D%0A%5Cbegin%7Bmarkdown%7D%0AThis+example+shows+how+to+import+a+graphics+file.+Here+we+are+using+an%0Aexample+image+provided+by+the+%60mwe%60+package.%0A%0A%25+Use+%5Csetkeys%7BGin%7D+if+you+need+to+change+an+image%27s+display+size%0A%0A%5Csetkeys%7BGin%7D%7Bwidth%3D.5%5Clinewidth%7D%0A%21%5BThis+is+alt+text+to+describe+my+image.%5D%28example-image.jpg+%22An+example+image+provided+by+the+%5Ctexttt%7Bmwe%7D+package.%22%29%0A%5Cend%7Bmarkdown%7D%0A%5Cend%7Bdocument%7D)
This example produces the following output:
#### Note on the image width
Like most packages, `markdown` loads other packages, including [`keyval`](https://ctan.org/pkg/keyval?lang=en) and [`graphicx`](https://ctan.org/pkg/graphicx?lang=en), 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:
```latex
\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](https://mirror.apps.cam.ac.uk/pub/tex-archive/macros/generic/markdown/markdown.html).
### Can you create tables using markdown in LaTeX? 😀
Unfortunately, no. Tables are supported in [MultiMarkdown](http://fletcherpenney.net/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](https://www.overleaf.com/gallery/tagged/tufte):
```latex
\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](https://www.overleaf.com/latex/examples/writing-beamer-slides-with-markdown/dnrwnjrpjjhw) and [posters](https://www.overleaf.com/latex/examples/writing-beamer-slides-with-markdown/dnrwnjrpjjhw)!
Have fun!
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://overleaf-pro.ayaka.space/latex/in-depth-articles/30-how-to-write-in-markdown-on-overleaf.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.