Markdown Basics

Introduction

This guide provides a comprehensive introduction to the basics of Markdown within Quarto, including a range of formatting options and advanced features to enhance your documentation projects.

Here’s what you’ll learn:

• Formatting text: Learn how to apply essential text styles like bold, italics, and headers to structure your document effectively.
• Creating lists: Understand how to organize information clearly using both unordered and ordered lists.
• Building tables: Get the know-how to assemble readable tables that improve data presentation.
• Incorporating media: Discover how to embed images, diagrams, and videos to make your content more engaging.
• Enhancing navigation: Use cross-references to link various parts of your documents seamlessly, improving the reader’s navigation experience.

This guide ensures you have all the tools needed to enhance your documentation, making it accessible and professionally formatted. Whether you’re compiling a technical report, educational material, or any extensive documentation, mastering these Markdown basics will significantly improve your ability to present information clearly and interactively.

Headings

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

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
• superscript² / subscript₂
• 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

2. 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 Code

| 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;
}
```

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 Code

:::{.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