Markdown Output

Overview

The Quarto visual editor generates markdown using Pandoc. This means that in some cases your markdown will be rewritten to conform to standard Pandoc idioms. For example, Pandoc inserts 3 spaces after list bullets and automatically escapes characters that might be used for markdown syntax.

Here is a list of conventions for Pandoc generated markdown that might differ from your own markdown writing style:

*text* is used in preference to _text_
Backtick code blocks are written as ``` {.md} rather than ```md
Backtick code blocks with no attributes are rendered as 4-space indented code blocks
Horizontal rules are written as dashes spanning the full width of the document
Plain links are written as <https://yihui.org> rather than https://yihui.org
Bullet and numbered lists use additional leading spaces before list item content
The blockquote character (>) is included on each new line of a blockquote
Table captions are written below rather than above tables
Multiline HTML and TeX blocks use the explicit raw attribute (e.g. ```{=tex})
Inline footnotes are replaced with footnotes immediately below the paragraph
Nested divs use ::: at all levels so long as their attributes are distinct
Unnumbered sections are designated with {.unnumbered} rather than {-}
Characters used for markdown syntax (e.g. *, _, or #) are always escaped

While some of this behavior might be bothersome at first, if you decide that visual editing mode is useful for your workflow it’s probably best to just adapt to writing your own markdown the same way that Pandoc does. Note that you can also configure source mode to write markdown using these conventions, ensuring that the same markdown is written no matter which mode edits originate from.

Writer Options

Some aspects of markdown output can be customized via global, project, or file-level options, including:

How to wrap / break lines (fixed column, sentence-per-line, etc.).
Where to write footnotes (below the current paragraph or section, or at the end of the document).
Whether to use the visual mode markdown writer when saving markdown from source mode (to ensure consistency between documents saved from either mode).

You can set these options within the R Markdown Global Options or Project Options, or can alternatively set them on a per-file basis using YAML (as described below).

Line Wrapping

By default, the visual editor writes Markdown with no line wrapping (paragraphs all occupy a single line). This matches the behavior of markdown source editing mode within RStudio.

However, if you prefer to insert line breaks at a particular column (e.g. 72 or 80), or to insert a line break after each sentence, you can set a global or per-project editor option to this effect.

You can also set this behavior on a per-document basis via the wrap option. For example, to wrap lines after 72 characters you would use this:

---
editor:
  markdown:
    wrap: 72
---

To insert a line break after each sentence, use wrap: sentence. For example:

---
editor:
  markdown:
    wrap: sentence
---

The algorithm used for sentence wrapping will handle English and Japanese text well, but may not detect the end of sentences accurately for other languages.

If you have enabled a global line wrapping option and want to turn off wrapping for a given document, use wrap: none.

References

By default, references are written at the end of the block where their corresponding footnote appears. You can override this behavior using the references option.

For example, to write references at the end of sections rather than blocks you would use:

---
title: "My Document"
editor:
  markdown:
    references: 
      location: block
---

Valid values for the references option are block, section, and document.

Note that you can also set a global or per-project editor option to control reference writing behavior.

If you are aggregating a set of markdown documents into a larger work, you may want to make sure that reference identifiers are unique across all of your documents (e.g. you don’t want to have [^1] appear multiple times). You can ensure uniqueness via the prefix option. For example:

---
title: "My Document"
editor:
  markdown:
    references: 
      location: block
      prefix: "mydoc"
---

This will result in footnotes in this document using the specified prefix (e.g. [^mydoc-1]), ensuring they are globally unique across the manuscript.

Note that if you are within a Quarto book project then a references prefix is applied automatically so no changes to editor: markdown are required.

Canonical Mode

If you have a workflow that involves editing in both visual and source mode, you may want to ensure that the same markdown is written no matter which mode edits originate from. You can accomplish this using the canonical option. For example:

---
title: "My Document"
editor:
  markdown:
    wrap: 72
    references: 
      location: block
    canonical: true
---

With canonical: true, edits in visual mode and source mode will result in identical markdown output. This is especially useful if you have multiple authors collaborating using version control, with a mixture of source and visual mode editing among the authors.

Known Limitations

There are a handful of Pandoc markdown extensions not currently supported by visual editing. These are infrequently used extensions, so in all likelihood they won’t affect documents you edit, but are still worth noting.

Extension(s)	Example	Behavior
Inline footnotes	^[inline]	Converted to numeric footnote.
Footnote identifiers	[^longnote]	Converted to numeric footnote.
Example lists	(@) First example	Read/written as ordinary numbered lists.
Auto-list numbers	#. First item	Read/written as ordinary numbered lists.
Reference links	This is a [link]	Converted to ordinary links.
MultiMarkdown attributes	# Heading [id]	Converted to Pandoc attributes.

The visual editor is unable to parse non-YAML title blocks (e.g. old-style % titles or MultiMarkdown titles) and also unable to parse non top-level YAML metadata blocks. If these forms of metadata are encountered, visual mode will fail to load with a warning.