04 - Static Quarto Documents

HTML Workhorse

quarto.org/docs/reference/formats/html

Quarto and RMarkdown

  • Basic RMarkdown documents that render to static HTML and PDF are the most transferable directly to Quarto

R Markdown

title: "My Document"
output:
  html_document:
    toc: true
    number_sections: true
    css: styles.css

Quarto

title: "My Document"
format:
  html:
    toc: true
    number-sections: true
    css: styles.css


One source of the difference in syntax is that Quarto is more closely aligned with Pandoc format names and options (thus the use of - as a word separator rather than _).

Our turn

  • Open materials/workshop/04-static/old-rmarkdown.rmd
  • Render via Quarto CLI

Static documents

  • A static document is your “daily driver” - has the power for a complex table of contents, figure alignment, control of ouptut/code, and other niceties
  • Useful as a lab notebook, scratchpad, or the final output for your team

Table of contents and Sections

Table of contents (ToC) and sections are useful for breaking up longer documents.

  • Quarto will automatically build a ToC for level 3 headers and above but you can control this with:
toc-depth: 4

or

toc-depth: 2

Tabsets

Split up and flip between sections of a page, alternative to just two columns

::: {.panel-tabset}

## Element 1

## Element 2

:::

Tabsets

```{r}
#| eval: false
head(mtcars)
```
                   mpg cyl disp  hp drat    wt  qsec vs am gear carb
Mazda RX4         21.0   6  160 110 3.90 2.620 16.46  0  1    4    4
Mazda RX4 Wag     21.0   6  160 110 3.90 2.875 17.02  0  1    4    4
Datsun 710        22.8   4  108  93 3.85 2.320 18.61  1  1    4    1
Hornet 4 Drive    21.4   6  258 110 3.08 3.215 19.44  1  0    3    1
Hornet Sportabout 18.7   8  360 175 3.15 3.440 17.02  0  0    3    2
Valiant           18.1   6  225 105 2.76 3.460 20.22  1  0    3    1

Tabsets


::: {.panel-tabset}

## Code

```{r}
#| echo: fenced
#| eval: false
head(mtcars)
```


## Output

```{r}
#| eval: true
#| echo: false
head(mtcars)
```

:::

Code

Hide all code

format: html
execute:
  echo: false

Turn back on at individual code-block level:

#| echo: true

Fold code

format:
  html:
    code-fold: true
    code-summary: "Hidden code"

Turn on at individual code-block level:

#| code-fold: true
#| code-summary: "Hidden code"

Code tools

format:
  html:
    code-fold: true
    code-tools: true

Code tools, source

For example, here we specify that we want only “View Source” (no toggling of code visibility) and no caption on the code menu:

format:
  html: 
    code-tools:
      source: true
      toggle: false
      caption: none

Code tools, source repo

In some situations (especially for longer documents), you may prefer to send viewers to the source code on a version-control website rather than the built in viewer.

format:
  html: 
    code-tools:
      source: https://github.com/quarto-dev/quarto-web/blob/main/index.md

Our turn

  • Open materials/workshop/04-static/penguin-report.qmd
  • Explore the document as a concept of literate programming or a “lab notebook”
  • Change the code to all fold, render
  • Change the code to source and toggle

Code linking with downlit

The goal of downlit is to provide syntax highlighting and automatic linking of R code

format:
  html:
    code-link: true

Aesthetics

HTML Appearance

Out of the box, Quarto is styled with Bootstrap 5 and opinionated defaults.

Bootstrap is the most popular CSS Framework for responsive websites, where v5 is the latest.

Quarto comes pre-installed with 25 themes from Bootswatch and you can use them like so:

---
format:
  html:
    theme: litera
---


Or you can customize a theme with CSS/SCSS/SASS.

---
format:
  html:
    theme: 
      - litera
      - custom.scss
---

Bootswatch themes

Bootswatch: lumen

Bootswatch: litera

Bootswatch: flatly

Bootswatch: sketchy

Our turn

  • Open materials/workshop/04-static/bootswatch-themed.qmd and try out some themes!
  • 25 bootswatch themes
  • https://quarto.org/docs/output-formats/html-themes.html
  • https://quarto.org/docs/output-formats/html-themes-more.html

CSS

CSS = Cascading Style Sheets:

CSS is a language for specifying how documents are presented to users — how they are styled, laid out, etc mdn web docs

HTML structures the page, CSS styles it

<div style="color: red; font-size: 100px;">Some text</div>
Some text

CSS can also bring in additional resources, like new fonts!

@import url('https://fonts.googleapis.com/css2?family=Fira+Mono&display=swap');

Inline css

:::{style="color: white; font-size: 150px; background-color:#d3d3d3;"}
Text
:::

Text

Some text with [dplyr code]{style="font-family: 'Fira Mono !important'; background-color:#d3d3d3;"} and more text.

Some text with code and more text.

CSS Class

.big-text {
  font-size: 150px;
  color: blue;
}
::: {.big-text}
- Big text
- Still big
:::

- Smol text
  • Big text
  • Still big
  • Smol text

Class + spans

Here is some [big text]{.big-text} and some small text.

Here is some big text and some small text.

format: PDF

TIP! - pandoc divs/spans are generally transferrable - CSS is not transferable - Lean on Quarto/Pandoc tooling and then reach for raw CSS/LaTeX

Our turn

  • Open materials/workshop/01-intro/history.qmd
  • Render as HTML and then render as PDF