Markdown Basics

Introduction

This guide provides an introduction to Markdown basics, covering essential formatting options such as headings, text styles (italics, bold, etc.), lists (unordered and ordered), tables, and special features like diagrams, video embedding, page breaks, and callout blocks. It’s designed to help users effectively style and structure their web content with Markdown, with examples and outputs for each feature, tailored for Quarto, a tool that enhances Markdown for technical and scientific documentation.



Headings

Markdown supports six levels of headings, with # representing the highest level (Header 1) and ###### the lowest level (Header 6).

Markdown Syntax:

Syntax:

# Header 1
## Header 2
### Header 3
#### Header 4
##### Header 5
###### Header 6

Output:

Header 1

Header 2

Header 3

Header 4

Header 5
Header 6

Text Formatting

Syntax:

- *italics*, **bold**, ***bold italics***
- superscript^2^ / subscript~2~
- ~~strikethrough~~
- `verbatim code`

Output:

  • italics, bold, bold italics
  • superscript2 / subscript2
  • strikethrough
  • verbatim code

Lists

Syntax:

* unordered list
    + sub-item 1
    + sub-item 2
        - sub-sub-item 1

Output:

  • unordered list
    • sub-item 1
    • sub-item 2
      • sub-sub-item 1

Syntax:

*   item 2
        
    Continued (indent 4 spaces)

Output:

  • item 2

    Continued (indent 4 spaces)

Syntax:

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

Output:

  1. ordered list
  2. item 2
    1. sub-item 1
      1. sub-sub-item 1

Syntax:

(@)  A list whose numbering
                   
continues after
                 
(@)  an interruption

Output:

  1. A list whose numbering

continues after

  1. an interruption

Syntax:

::: {}
1. A list
:::
::: {}
1. Followed by another list
:::

Output:

  1. A list
  1. Followed by another list

Syntax:

term
: definition

Output:

term
definition

Note that unlike other Markdown renderers (notably Jupyter and GitHub), lists in Quarto require an entire blank line above the list. Otherwise the list will not be rendered in list form, rather it will all appear as normal text along a single line.

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

Diagrams

Quarto has native support for embedding Mermaid and Graphviz diagrams.

Live editors to improve your productivity authoring diagrams:

  1. The Mermaid Live Editor is an online tool for editing and previewing Mermaid diagrams in real time.
  2. Graphviz Online provides a similar tool for editing Graphviz diagrams.

Create a flowchart 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]

A simple undirected graph created using graphviz:

```{dot}
graph G {
  layout=neato
  run -- intr;
  intr -- runbl;
  runbl -- run;
  run -- kernel;
  kernel -- zombie;
  kernel -- sleep;
  kernel -- runmem;
  sleep -- swap;
  swap -- runswap;
  runswap -- new;
  runswap -- runmem;
  new -- runmem;
  sleep -- runmem;
}
```

G run run intr intr run--intr kernel kernel run--kernel runbl runbl intr--runbl runbl--run zombie zombie kernel--zombie sleep sleep kernel--sleep runmem runmem kernel--runmem sleep--runmem swap swap sleep--swap runswap runswap swap--runswap runswap--runmem new new runswap--new new--runmem

Read more about diagrams in Quarto.

Videos

Include a video from YouTube:

{{< video https://www.youtube.com/embed/wo9vZccmqwc >}}

Additional examples that demonstrate using various video sources and options:

{{< video local-video.mp4 >}}

{{< video https://www.youtube.com/embed/wo9vZccmqwc >}}

{{< video https://youtu.be/wo9vZccmqwc width="400" height="300" >}}

{{< video https://www.youtube.com/embed/wo9vZccmqwc
    title="What is the CERN?"
    start="116"
    aspect-ratio="21x9" 
>}}

Read more about videos in Quarto.

Page Breaks

Insert a page break with the pagebreak shortcode:

page 1

{{< pagebreak >}}

page 2

Native pagebreaks are supported for HTML, LaTeX, Context, MS Word, Open Document, and ePub.

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.

Tip

This is a tip.

Warning

This is a warning.

Caution

This is a caution.

Important

This is important.

Code annotations

Code cell annotations involve:

  1. Ending each annotated line with a comment and an annotation number in angle brackets (like # <2>). Use the same number to span an annotation over multiple lines.
  2. Adding an ordered list right after the code cell, where each item matches an annotation number in the code.

Syntax:

```r
x <- 1:10  # <1>
y <- x^2   # <2>
z <- x^3   # <2>
```
1. Create a vector `x`, and then,
2. compute `y` and `z` 

Output:

1x <- 1:10
2y <- x^2
z <- x^3
1
Create a vector x, and then,
2
compute y and z

Possible annotation positions for HTML output are:

  • below (default): Annotations appear below the code cell by default.
  • hover: Annotations show on mouse hover over a line marker.
  • select: Annotations appear when a marker is clicked and can be dismissed by clicking again.

To change the default annotation position, use the code-annotations metadata field in the document header:

---
code-annotations: hover
---

References

Quarto Markdown Basics