> 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/32-markdown-into-latex-with-style.md). # 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`](http://www.ctan.org/pkg/markdown) 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](/latex/in-depth-articles/30-how-to-write-in-markdown-on-overleaf.md) 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](/latex/in-depth-articles/30-how-to-write-in-markdown-on-overleaf.md) 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](/latex/in-depth-articles/30-how-to-write-in-markdown-on-overleaf.md) gave some examples of using markdown in [Beamer presentations](https://www.overleaf.com/read/dnrwnjrpjjhw) and [posters](https://www.overleaf.com/read/jtbgmmgqrqmh): 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](https://www.overleaf.com/latex/templates/the-legrand-orange-book-template-english/jtctyfmnpppc) template * The [Tufte-inspired handout](https://www.overleaf.com/latex/templates/handout-design-inspired-by-edward-tufte/dtsbhhkvghzz) template * This [very nice article template](https://www.overleaf.com/read/xfsrpsmdtqvt) by Thiago You may notice that two of these are article templates and one is a book template. The [`markdown package`](http://www.ctan.org/pkg/markdown) 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](https://www.overleaf.com/read/nqbhpnrkskrx) 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](https://www.overleaf.com/read/zfzcxygqwqsq) or a little [picture story book](https://www.overleaf.com/read/rppnsfgnrhsf). 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`](http://www.ctan.org/pkg/markdown) 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: {% embed url="" %} ### 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: ```latex \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](https://www.overleaf.com/read/gscqdhnwzsfg) that you can write with markdown *and* make into a mini-booklet. [![A recipe booklet produced on Overleaf using markdown](/files/jEuWlUaETmUOd5pzEBqR)](https://www.overleaf.com/read/gscqdhnwzsfg) 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](http://texdoc.net/pkg/markdown). `\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](https://www.overleaf.com/read/whdrnpcpnwrm). --- # 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/32-markdown-into-latex-with-style.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.