Markdown Basics

Overview

Quarto is based on Pandoc and uses its variation of markdown as its underlying document syntax. Pandoc markdown is an extended and slightly revised version of John Gruber’s Markdown syntax.

Markdown is a plain text format that is designed to be easy to write, and, even more importantly, easy to read:

A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. – John Gruber

This document provides examples of the most commonly used markdown syntax. See the full documentation of Pandoc’s Markdown for more in-depth documentation.

Text Formatting

Markdown Syntax Output
*italics* and **bold**
italics and bold
superscript^2^ / subscript~2~
superscript2 / subscript2
~~strikethrough~~
strikethrough
`verbatim code`
verbatim code

Headings

Markdown Syntax Output
# Header 1

Header 1

## Header 2

Header 2

### Header 3

Header 3

#### Header 4

Header 4

##### Header 5
Header 5
###### Header 6
Header 6

Lists

Markdown Syntax Output
* unordered list
    + sub-item 1
    + sub-item 2
        - sub-sub-item 1
  • unordered list

    • sub-item 1

    • sub-item 2

      • sub-sub-item 1
*   item 2

    Continued (indent 4 spaces)
  • item 2

    Continued (indent 4 spaces)

1. ordered list
2. item 2
    i) sub-item 1
         A.  sub-sub-item 1
  1. ordered list

  2. item 2

    1. sub-item 1

      1. sub-sub-item 1
(@)  A list whose numbering

continues after

(@)  an interruption
  1. A list whose numbering

continues after

  1. an interruption
term
: definition
term

definition

Tables

Markdown Syntax

| Right | Left | Default | Center |
|------:|:-----|---------|:------:|
|   12  |  12  |    12   |    12  |
|  123  |  123 |   123   |   123  |
|    1  |    1 |     1   |     1  |

Output

Right Left Default Center
12 12 12 12
123 123 123 123
1 1 1 1

Learn more in the article on Tables.

Source Code

Use ``` to delimit blocks of source code:

```
code
```

Add a language to syntax highlight code blocks:

```python
1 + 1
```

Pandoc supports syntax highlighting for over 140 different languages. If your language is not supported then you can use the default langauge to get a similar visual treatment:

```default
code
```

If you are creating HTML output there is a wide variety of options available for code block output. See the article on HTML Code for additional details.

Equations

Use $ delimiters for inline math and $$ delimiters for display math. For example:

Markdown Syntax Output
inline math: $E = mc^{2}$
inline math: \(E=mc^{2}\)
display math:

$$E = mc^{2}$$
display math:
\[E = mc^{2}\]

If you want to define custom TeX macros, include them within $$ delimiters enclosed in a .hidden block. For example:

::: {.hidden}
$$
 \def\RR{{\bf R}}
 \def\bold#1{{\bf #1}}
$$
:::

For HTML math processed using MathJax (the default) you can use the \def, \newcommand, \renewcommand, \newenvironment, \renewenvironment, and \let commands to create your own macros and environments.

Diagrams

Quarto has native support for embedding Mermaid and Graphviz diagrams. This enables you to create flowcharts, sequence diagrams, state diagrams, gnatt charts, and more using a plain text syntax inspired by markdown.

For example, here we embed a flowchart created using Mermaid:

```{mermaid}
flowchart LR
  A[Hard edge] --> B(Round edge)
  B --> C{Decision}
  C --> D[Result one]
  C --> E[Result two]
```

flowchart LR
  A[Hard edge] --> B(Round edge)
  B --> C{Decision}
  C --> D[Result one]
  C --> E[Result two]

Learn more in the article on Diagrams.

Page Breaks

The pagebreak shortcode enables you to insert a native pagebreak into a document (.e.g in LaTeX this would be a \newpage, in MS Word a docx-native pagebreak, in HTML a page-break-after: always CSS directive, etc.):

page 1

{{< pagebreak >}}

page 2

Native pagebreaks are supported for HTML, LaTeX, Context, MS Word, Open Document, and ePub (for other formats a form-feed character \f is inserted).

Divs and Spans

You can add classes, attributes, and other identifiers to regions of content using Divs and Spans (you’ll see an example of this below in Callout Blocks).

For example, here we add the “border” class to a region of content using a div (:::):

::: {.border}
This content can be styled with a border
:::

Divs start with a fence containing at least three consecutive colons plus some attributes. The attributes may optionally be followed by another string of consecutive colons. The Div ends with another line containing a string of at least three consecutive colons. The Div should be separated by blank lines from preceding and following blocks. Divs may also be nested. For example

::::: {#special .sidebar}

::: {.warning}
Here is a warning.
:::

More content.
:::::

Fences without attributes are always closing fences. Unlike with fenced code blocks, the number of colons in the closing fence need not match the number in the opening fence. However, it can be helpful for visual clarity to use fences of different lengths to distinguish nested divs from their parents.

A bracketed sequence of inlines, as one would use to begin a link, will be treated as a Span with attributes if it is followed immediately by attributes:

[This is *some text*]{.class key="val"}

Typically, you’ll use CSS and/or a Filter along with Divs and Spans to provide styling or other behavior within rendered documents.

See the Pandoc documentation on Divs and Spans for additional details.

Callout Blocks

Markdown Syntax

:::{.callout-note}
Note that there are five types of callouts, including: 
`note`, `tip`, `warning`, `caution`, and `important`.
:::

Output

Note

Note that there are five types of callouts, including note, tip, warning, caution, and important.

Learn more in the article on Callout Blocks.

Other Blocks

Markdown Syntax Output
> Blockquote

Blockquote

::: {.classname}
Div
:::

Div

| Line Block
|   Spaces and newlines
|   are preserved

Line Block
   Spaces and newlines
   are preserved

Special Characters

Markdown Syntax Output
endash: --
endash: –
emdash: ---
emdash: —