Quarto Documents

Anatomy of a Quarto document

• Anatomy of a Quarto document

• Authoring Quarto

• Changing formats

Anatomy of a Quarto document

.qmd file format with three components:

1. YAML: Metadata

2. Text: Markdown

3. Code: R, Python, Observable, and Julia

Weave it all together, and you have beautiful, powerful, and useful outputs!

A Quarto document contains three types of content: a YAML header, code chunks, and markdown text.

Anatomy of a Quarto document

Metadata: YAML

my-document.qmd

---
title: "The Story of America's Dam Infrastructure"
format: html
---

• “Yet another markup language”
• Metadata of your document
• Demarcated by three dashes (---) on either end
• Uses key-value pairs in the format key: value

Quarto documents usually start with an (optional) YAML header demarcated by three dashes on either end. The basic syntax of YAML uses key-value pairs in the format key: value. It controls the output of the document and contain metadata for your document. YAML fields commonly found in headers of documents include metadata like author, subtitle, date as well as customization options like theme, fontcolor, fig-width, etc.

Anatomy of a Quarto document

Text: Markdown

my-document.qmd

---
title: "The Story of America's Dam Infrastructure"
format: html
---

This analysis explores the National Inventory of Dams (NID) dataset.

• Markdown is a lightweight language for creating formatted text
• Quarto is based on Pandoc and uses its variation of markdown as its underlying document syntax

Markdown is a lightweight markup language for creating formatted text using a plain-text editor. Quarto uses markdown syntax for text.

Anatomy of a Quarto document

Text: Markdown

The `nation.csv` dataset records the [**National Inventory of Dams (NID)**](https://nid.sec.usace.army.mil) information.

The nation.csv dataset records National Inventory of Dams (NID) information.

Anatomy of a Quarto document

Text: Markdown

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

Anatomy of a Quarto document

Code

my-document.qmd

---
title: "The Story of America's Dam Infrastructure"
format: html
---

This is [**National Inventory of Dams (NID)**](https://nid.sec.usace.army.mil) data.

```{python}
from plotnine import ggplot, aes, geom_bar

(
    ggplot(mpg, aes(x = "state", y = "dams"))
    + geom_bar()
)
```

Anatomy of a Quarto document

Code

my-document.qmd

---
title: "The Story of America's Dam Infrastructure"
format: html
---

This is [**National Inventory of Dams (NID)**](https://nid.sec.usace.army.mil) data.

```{python}
from plotnine import ggplot, aes, geom_bar

(
    ggplot(mpg, aes(x = "state", y = "dams"))
    + geom_bar()
)
```

• Code chunks begin and end with three backticks (usually)
• Code chunks are identified with a programming language in between {}

Code chunks are identified with three backticks, the language in curly brackets, and can have optional chunk options identified by the hashpipe at the beginning of the line within the chunk.

Anatomy of a Quarto document

Inline code executes code within Markdown

my-document.qmd

```{python}
dams = 92428
```

The number of dams is `{python} dams`.

Results in:

The number of dams is 92428.

Anatomy of a Quarto document

Code can include optional chunk options, in YAML style, identified by #| at the beginning of the line

---
title: "The Story of America's Dam Infrastructure"
format: html
---

This is [**National Inventory of Dams (NID)**](https://nid.sec.usace.army.mil) data.

```{python}
#| echo: false
from plotnine import ggplot, aes, geom_bar

(
    ggplot(mpg, aes(x = "state", y = "dams"))
    + geom_bar()
)
```

Code chunks can have optional chunk options identified by the hashpipe at the beginning of the line within the chunk.

Anatomy of a Quarto document

Code can include optional chunk options, in YAML style, identified by #| at the beginning of the line

---
title: "The Story of America's Dam Infrastructure"
format: html
---

This is [**National Inventory of Dams (NID)**](https://nid.sec.usace.army.mil) data.

```{python}
#| include: false
#| fig.alt: "A scatterplot with state on the x-axis and dams on the y-axis."
from plotnine import ggplot, aes, geom_bar

(
    ggplot(mpg, aes(x = "state", y = "dams"))
    + geom_bar()
)
```

Anatomy of a Quarto document

Code can include optional chunk options, in YAML style, identified by #| at the beginning of the line

Option	Description
eval	Evaluate the code chunk
echo	Include the source code
warning	Include warnings
include	Include code and results

Other options: https://quarto.org/docs/computations/execution-options.html

Your turn

• Open 01-exercise-r.qmd and run the first three code chunks (in order).
• Preview the file.
• Add a #| include: false chunk option to the first cell. Preview the file and note the differences.
• In the YAML, add an author field and add your name. Preview the file.
• Change code-fold to be true. Preview the file.
• Edit the first paragraph to (1) make something bold by surrounding the text with ** and (2) use inline code instead of hardcoded values for the number of dams:

• R
• Python

`r format(nrow(dat), big.mark = ",")`

`{python} f"{total_dams:,}"`

05:00

Authoring Quarto

• Anatomy of a Quarto document

• Authoring Quarto

• Changing formats

Images and links

Markdown syntax	Output
<https://quarto.org>	https://quarto.org
[Quarto](https://quarto.org)	Quarto


Tables

```{markdown}
| Right | Left | Default | Center |
|------:|:-----|---------|:------:|
|    12 | 12   | 12      |   12   |
|   123 | 123  | 123     |  123   |
|     1 | 1    | 1       |   1    |
```

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

Tables

```{markdown}
| Right | Left | Default | Center |
|------:|:-----|---------|:------:|
|    12 | 12   | 12      |   12   |
|   123 | 123  | 123     |  123   |
|     1 | 1    | 1       |   1    |

: Table Column Widths {tbl-colwidths="[10,30,30,30]"}
```

Table Column Widths

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

Diagrams

```{mermaid}
%%| fig-width: 6
flowchart LR
  A[1] --> B(2)
  B --> C{3}
  C --> D[4]
  C --> E[5]
```

flowchart LR
  A[1] --> B(2)
  B --> C{3}
  C --> D[4]
  C --> E[5]

There is also native support for diagrams, where the syntax is similar as R or Python where the execution is being run by Quarto. This is a Mermaid diagram, which is a newer project supported on GitHub where you can use it in their documents as well, so it’s a pretty handy tool to get to know.

Equations

```{markdown}
$$E = mc^{2}$$
```

\[E = mc^{2}\]

Math mode in LaTeX

Divs and Spans

Divs

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

Spans

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

This is some text

For furture customization, you can add classes, attributes, and other identifiers to content using Divs and Spans. Some are built into Quarto, and you can define your own, as well.

Divs

Callout blocks

my-document.qmd

:::{.callout-tip}

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

:::

Tip

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

Divs

Multiple columns

my-document.qmd

::: {layout-ncol=2}

![](dam.jpg)

Photo by <a href="https://unsplash.com/@dmey503?utm_content=creditCopyText&utm_medium=referral&utm_source=unsplash">Dan Meyers</a> on <a href="https://unsplash.com/photos/aerial-photography-of-body-of-water-w6X7XaolqA0?utm_content=creditCopyText&utm_medium=referral&utm_source=unsplash">Unsplash</a>
:::

Photo by Dan Meyers on Unsplash

Divs

Tabsets

my-document.qmd

::: {.panel-tabset group="language"}
## R

`library(dplyr)`

## Python

`import pandas as pd`
:::

• R
• Python

library(dplyr)

import pandas as pd

Spans

my-document.qmd

This is text that is [red]{style="color:red;"}.

This is text that is red.

my-document.qmd

![](dam.jpg){fig-alt="A photo of a dam in Detroit"}

You can also apply styles to inline text by creating spans. Use square brackets to surround the text and curly bracketes for the style you would like.

Changing formats

• Anatomy of a Quarto document

• Authoring Quarto

• Changing formats

Changing formats

my-document.qmd

---
title: "The Story of America's Dam Infrastructure"
format: html
---

Changing formats

my-document.qmd

---
title: "The Story of America's Dam Infrastructure"
format: revealjs
---

Changing formats

my-document.qmd

---
title: "The Story of America's Dam Infrastructure"
format: pdf
---

Your turn

• Add an important callout box to “Key Findings at a Glance”:

::: {.callout-important}
_text here_
:::

• Change the format to revealjs. Preview the document.
• Change the format to pdf. Preview the document.

Note

Removing code-fold, code-summary, and embed-resources is not required because these are html only features. However, I’d recommend removing them to keep your document tidy.

05:00