Polishing Documents

Workshop: Quarto for R & RStudio
posit::conf 2023

Element Attributes

What happens when you pandoc it?

From the last exercise . . .

quarto pandoc -f html -t markdown 3-markdow-goal.html -o answer.md

This looks familiar!

What happens when you pandoc it?

From the last exercise . . .

quarto pandoc -f html -t markdown 3-markdow-goal.html -o answer.md

This looks familiar!

. . . but this does not.

The Bracketed Span

The Fenced Div

Figures

Poll

What is your preferred method of adding a figure to an Rmd so that it displays in HTML at 300 pixels wide?

A. markdown

![A nice image.](foo/bar.png){width=300}

B. html

<img src="foo/bar.png" width="300">

C: knitr

```{r, out.width="300px"}
knitr::includegraphics("foo/bar.png")
```

Attributes

Set width, height, fig-align, add link, and alt-text (captions go inside []).

![](images/dog-watch.png){width=300 fig-align=right}

Units default to px.
Other choices 300in, 300% (relative to image size), 3em (relative to font size).
Entire fig can be nested inside the link syntax ([fig](url)) to link the image

Internal links

In additional to external resources, links can go to elements of the same doc through its #id.

Markdown

![A caption](images/dog-watch.png){#dog}

< Much more text >

A novelty clock, [watch](#dog), 
and the like for keeping time 
at an animal's rate . . .

HTML output

< Much more text >

A novelty clock, watch, and the like for keeping time at an animal’s rate . . .

Works for many elements,
not just figs!

Tables

Markdown tables

Markdown:

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

: Sample markdown table. {#mytab}

Output:

Sample markdown table. {#mytab}
Right	Left	Default	Center
12	12	12	12
123	123	123	123
1	1	1	1

Grid tables

Markdown:

+---------------+---------------+--------------------+
| Fruit         | Price         | Advantages         |
+===============+===============+====================+
| Bananas       | $1.34         | - built-in wrapper |
|               |               | - bright color     |
+---------------+---------------+--------------------+
| Oranges       | $2.10         | - cures scurvy     |
|               |               | - tasty            |
+---------------+---------------+--------------------+

: Sample grid table.

Tables from code

The knitr package can turn data frames into tables with knitr::kable():

library(knitr)
library(dplyr)
library(palmerpenguins)

s_penguins <- penguins |> 
  select(species,
         island,
         bill_length_mm) |>
  slice(1:5)

s_penguins |>
  kable()

species	island	bill_length_mm
Adelie	Torgersen	39.1
Adelie	Torgersen	39.5
Adelie	Torgersen	40.3
Adelie	Torgersen	NA
Adelie	Torgersen	36.7

Tables from code

If you want fancier tables, try the gt package and all that it offers!

library(gt)

s_penguins |> 
  gt() |>
  tab_style(
    style = list(
      cell_fill(color = "pink"),
      cell_text(style = "italic")
      ),
    locations = cells_body(
      columns = bill_length_mm,
      rows = bill_length_mm > 40
    )
  )

species	island	bill_length_mm
Adelie	Torgersen	39.1
Adelie	Torgersen	39.5
Adelie	Torgersen	40.3
Adelie	Torgersen	NA
Adelie	Torgersen	36.7

Cross references

Help readers to navigate your document with numbered references and hyperlinks to entities like figures and tables.
Cross referencing steps:
1. Add a caption to your figure or table.
2. Give an id to your figure or table, starting with fig- or tbl-.
3. Refer to it with @fig-... or @tbl-....

Figure cross references

The presence of the caption (Dog watch) and label (#fig-dog-watch) make this figure referenceable:

Markdown:

See @fig-dog-watch for a dog wearing a watch.
![Dog watch](images/dog-watch.png){#fig-dog-watch}

Output:

See Figure 1 for a dog wearing a watch.

Table cross references (from code)

The presence of the caption (A few penguins) and label (#tbl-penguins) make this table referenceable:

Markdown:

See @tbl-penguins for data on a few penguins.

```{r}
#| label: tbl-penguins
#| tbl-cap: A few penguins

head(penguins) |> 
  gt()
```

Output:

See Table 1 for data on a few penguins.

Table 1:
A few penguins
species	island	bill_length_mm	bill_depth_mm	flipper_length_mm	body_mass_g	sex	year
Adelie	Torgersen	39.1	18.7	181	3750	male	2007
Adelie	Torgersen	39.5	17.4	186	3800	female	2007
Adelie	Torgersen	40.3	18.0	195	3250	female	2007
Adelie	Torgersen	NA	NA	NA	NA	NA	2007
Adelie	Torgersen	36.7	19.3	193	3450	female	2007
Adelie	Torgersen	39.3	20.6	190	3650	male	2007

Table cross references (from markdown)

The presence of the caption (Numbers) and label (#tbl-numbers) make this table referenceable:

Markdown:

See @tbl-numbers for data.

| Right | Left |
|------:|:-----|
|   12  |  12  |
|  123  |  123 |

: Numbers {#tbl-numbers}

Output:

See Table 2 for data.

Table 2: Numbers
Right	Left
12	12
123	123

Your Turn

Open 1-tables-figures.qmd.

Create a 3 row x 2 col markdown table, populate with a column for restaurant + column for cuisine, and then add 3 examples. Then, cross reference it from text.
Include and image from the images/ folder and set its width.
Add a figure generated from code and cross reference it.
```
hist(rnorm(100))
```

07:00

Callout Blocks

Example: Callout Blocks

Use case: highlight content for the reader in multiple formats.

Markdown

:::{.callout-note}
Look - a squirrel!
:::

:::{.callout-important}
Look - a squirrel!
:::

:::{.callout-tip}
Look - a squirrel!
:::

HTML output

Note

Look - a squirrel!

Important

Look - a squirrel!

Tip

Look - a squirrel!

Callout Blocks

Highlight content for the reader in multiple formats.

Markdown

:::{.callout-note}
Look - a squirrel!
:::

:::{.callout-important}
Look - a squirrel!
:::

:::{.callout-tip}
Look - a squirrel!
:::

pdf output

Callout Blocks

Highlight content for the reader in multiple formats.

Markdown

:::{.callout-note}
Look - a squirrel!
:::

:::{.callout-important}
Look - a squirrel!
:::

:::{.callout-tip}
Look - a squirrel!
:::

docx output

Layouts

Element Layouts

Quarto makes available several layout attributes that apply to broad range of block elements.

layout-ncol: split elements across n columns (2, 3, …).
layout-nrow: split elements across n rows (2, 3, …).
layout-valign: align elements (top, center, bottom, default).
layout: Split elements into a 2D array by rows and columns¹.

Element Layouts

layout-ncol

Markdown

:::{layout-ncol=2}
A clock for keeping time at 
an animal's rate. The multiple
for dogs is seven, for example.

![](images/dog-watch.png)
:::

HTML output

A clock for keeping time at an animal’s rate. The multiple for dogs is seven, for example.

Element Layouts

layout-ncol + layout-valign

Markdown

:::{layout-ncol=2 layout-valign=middle}
A clock for keeping time at 
an animal's rate. The multiple
for dogs is seven, for example.

![](images/dog-watch.png)
:::

HTML output

A clock for keeping time at an animal’s rate. The multiple for dogs is seven, for example.

Element Layout Array

layout: The layout attribute¹ is a 2-dimensional array where the first dimension defines rows and the second columns.

layout="[[1,1], [1]]" translates to: create two rows, the first of which has two columns of equal size and the second of which has a single column.
You can scale the relative dimension of each panel by changing the 1s.

Element Layout Array

Markdown

:::{layout="[[1,1], [1]]"}
![](images/watch-face.png)

![](images/dog-watch.png)

![](images/circuit.png)
:::

HTML output

What would layout="[[1,5], [1]]" do?

Element Layout Array

Markdown

:::{layout="[[1,5], [1]]"}
![](images/watch-face.png)

![](images/dog-watch.png)

![](images/circuit.png)
:::

HTML output

Document Layout: column classes

Modify the width of the main body column for individual block elements (e.g. paragraph, figures). .column-body is the default.

Markdown

:::{.column-body}
A novelty clock, watch, and the like for 
keeping time at an animal's rate, defined
in terms of a multiple of human rate by 
dividing the average lifetime of a 
particular animal into the average 
lifetime of a human being. The multiple
for dogs is seven, for example.
:::

:::{.column-screen}
A novelty clock, watch, and the like for 
keeping time at an animal's rate, defined
in terms of a multiple of human rate by 
dividing the average lifetime of a 
particular animal into the average 
lifetime of a human being. The multiple
for dogs is seven, for example.
:::

HTML output

Document Layout: margin classes

Place any inline or block element from the body to the margin.

Markdown

![](images/dog-watch.png)

What a brilliant idea.

Output

Document Layout: margin classes

Place any inline or block element from the body to the margin.

Markdown

![](images/dog-watch.png)

:::{.column-margin}
What a brilliant idea.
:::

Output

Your Turn

Open 2-layouts.qmd and follow the directions to create a document that describes your favorite place to visit on vacation.

When you’re done, please share a screenshot of your document in Discord.

On your way out the door for lunch, please write on the blue sticky note one that confused or frustrated you and on the pink sticky something that you enjoyed, or got your excited.