Intro to Quarto

R-Ladies Baltimore | March 12, 2024

Isabella Velásquez

Introduction

Agenda

1. Introduction

2. Setting Up Quarto

3. Getting Started with Quarto

4. Creating Projects

5. Styling Quarto

6. Publishing Quarto

7. Conclusion

Hello!

My name is Isabella Velásquez.

@ivelasq

@ivelasq3

@ivelasq3

ivelasq.rbind.io

Hi everybody! Thank you so much for joining today’s session. I am so excited to introduce Quarto and many thanks to Margaret and the R-Ladies Baltimore co-organizers for having me today.

Resources

• Slides: https://ivelasq.quarto.pub/intro-to-quarto-2024/
• Exercise repo: https://github.com/ivelasq/intro-to-quarto-exercises
• rstudio.cloud Project: https://rstudio.cloud/content/4823293

Requirements

To follow along with the exercises, please be sure that you:

• Are on the latest version of RStudio v2023.12 or later and have cloned the exercise repo
• Or, have a rstudio.cloud account and can access the project
• And, have a https://quartopub.com/ account.

What is Quarto®?

Quarto is an

open-source

scientific and technical

publishing system

built on Pandoc.

Quarto is an open-source scientific and technical publishing system built on Pandoc. Open-source: RStudio believes that it’s better for everyone if the tools used for research and science are free and open. Free software in science means more reproducibility, widespread sharing of knowledge and techniques, and elimination of cost barriers. You can also see the source code and contribute, too. Scientific and technical: Scientific and technical means that Quarto has specific things for journal articles or scientific papers, like support for code execution, citations, footnotes, scientific markdown, equations, citations, crossrefs, figure panels, callouts, advanced layout, and more. We’ll be showing some of these later on. Publishing system: With Quarto, you can create dynamic content with Python, R, Julia, and Observable. Quarto takes rendered plain text like R Markdown files or mixed formats like Jupyter notebooks to create high-quality articles, reports, presentations, websites, blogs, and books in HTML, PDF, MS Word, ePub, and more. Pandoc: special flavor of markdown with high-quality feature set.

Quarto Origins

• At its core, Quarto is multilingual and independent of computational systems

• Has expanded upon R Markdown to add new languages and can add more in the future

Let’s bring R Markdown to everyone!

R Markdown is a file format for making dynamic documents with R. However, it is dependent on knitr and you need to call it from R to use it. If you’re a Python user, it means you need to install R to use R Markdown. Quarto is independent from the computational systems. Quarto supports knitr, and can support others. So, you can think of Quarto as the next generation R Markdown that is fundamentally multilanguage and multiengine.

Check out JJ Allaire’s R Medicine Keynote!

Quarto Engines

Quarto Workflow

An engine is the tool that runs code. This is the basic structure that creates documents from the source, the Quarto markdown file or the QMD file. When we render a Quarto document, first, the knitr engine executes all of the code chunks and generates an intermediary markdown file that includes both the code and code output. Then that markdown file is processed by pandoc to create the finished document. Since Quarto uses knitr, most Rmd files can be used unmodified.

Quarto Engines

knitr

---
title: "ggplot2 demo"
format: 
  html:
    code-fold: true
---

## Meet Quarto

Quarto enables you to weave together content and executable code into a finished document. To learn more about Quarto see <https://quarto.org>.

```{r}
#| label: plot-penguins
#| echo: false
#| message: false
#| warning: false

library(tidyverse)
library(palmerpenguins)

ggplot(penguins, 
       aes(x = flipper_length_mm, y = bill_length_mm)) +
  geom_point(aes(color = species, shape = species)) +
  scale_color_manual(values = c("darkorange","purple","cyan4")) +
  labs(
    title = "Flipper and bill length",
    subtitle = "Dimensions for penguins at Palmer Station LTER",
    x = "Flipper length (mm)", y = "Bill length (mm)",
    color = "Penguin species", shape = "Penguin species"
  ) +
  theme_minimal()
```

This is a Quarto document with the extension .qmd (on the left) along with its rendered version as HTML (on the right). You could also choose to render it into other formats like PDF, MS Word, etc. This is the basic model for Quarto publishing—take a source document and render it to a variety of output formats. Since it uses knitr, most Rmd files can be used unmodified.

Quarto Engines

Jupyter

---
title: "Palmer Penguins Demo"
format: 
    html:
        code-fold: true
jupyter: python3
---

## Meet Quarto

Quarto enables you to weave together content and executable code into a finished document. To learn more about Quarto see <https://quarto.org>.

```{python}
#| echo: false
#| message: false

import pandas as pd
import seaborn as sns 
from palmerpenguins import load_penguins
sns.set_style('whitegrid')

penguins = load_penguins()

g = sns.lmplot(x="flipper_length_mm",
               y="body_mass_g",
               hue="species",
               height=7,
               data=penguins,
               palette=['#FF8C00','#159090','#A034F0']);
g.set_xlabels('Flipper Length');
g.set_ylabels('Body Mass');
```

The structure is similar for Jupyter, we just are running documents natively through the Jupyter engine. Like R Markdown, you can render Jupyter notebooks with Quarto, too. Jupyter will support any other language that has a Jupyter kernal, and right now, there’s a lot of Quarto functionality for Python and Julia through Jupyter. Send to Jupyter engine (instead of knitr) to create markdown Will support traditional .ipynb notebooks as well But, this is part of the multilingualism that we discussed earlier, where you can keep adding languages if you swap out different engines. This also means you can have a shared syntax and format across languages, since the backend is the same.

Quarto Formats

Websites

---
title: Home
pagetitle: nbdev – Create delightful software with Jupyter Notebooks
page-layout: custom
section-divs: false
css: index.css
toc: false
image: https://nbdev.fast.ai/images/card.png
description: Write, test, document, and distribute software packages and technical articles —        all in one place, your notebook.
---

from fastcore.foundation import L
from nbdev import qmd

def img(fname, classes=None, **kwargs): return qmd.img(f"images/{fname}", classes=classes,     **kwargs)
def btn(txt, link): return qmd.btn(txt, link=link, classes=['btn-action-primary', 'btn-action',     'btn', 'btn-success', 'btn-lg'])
def banner(txt, classes=None, style=None): return qmd.div(txt, L('hero-banner')+classes,     style=style)

features = L(
    ('docs', 'Beautiful technical documentation and scientific articles with Quarto'),
    ('testing', 'Out-of-the-box continuous integration with GitHub Actions'),
    ('packaging', 'Publish code to PyPI and conda, and prose to GitHub Pages'),
    ('vscode', 'Two-way sync with your favourite IDEs'),
    ('jupyter', 'Write prose, code, and tests in notebooks — no context-switching'),
    ('git', 'Git-friendly notebooks: human-readable merge conflicts; no unwanted metadata')
)

nbdev.fast.ai

Quarto Formats

Blogs

https://jollydata.blog/

Books

Python for Data Analysis, 3E by Wes McKinney

Quarto Formats

Presentations

The untold story of palmerpenguins by Dr. Kristen Gorman, Dr. Allison Horst, and
Dr. Alison Hill

Journals

Journal of Statistical Software (JSS)

Quarto Formats

Dashboards (NEW!)

Dashboard by Mine Çetinkaya-Rundel

Why Quarto?

A unified ecosystem

• R Markdown has a lot of packages doing lots of different things

• Quarto has a shared expression for core features

So this is all good and well, but you may be wondering should you switch to Quarto if you already have another tool that you really like, you may be wondering whether or not you should switch. Here are some considerations. Quarto has a shared expression for core features. If you used the packages from the R Markdown ecosystem, then you may have had to switch between different ways of doing the same thing. NEXT In Quarto, you have a shared core syntax that is the same across all formats. Things like tabset, code folding, cross references in the same way. Another example is that Quarto has a universal theming system based on SCSS for all HTML output where core variables defined by bslib and so it is compatible with Shiny, flexdashboard, and R Markdown themes. So, users can create very consistent and organized theming across content

Why Quarto?

New features

• Cross references
• Advanced layout
• Figure/layout panels
• Callouts
• Diagrams
• Extensions
• Interactivity
• YAML intelligence
• Publishing
• Conditional content
• Notebook filters

R Markdown isn’t going away but big new features will be in Quarto, things like YAML intelligence, figure panels, layouts, which we’ll cover later in the session.

Why Quarto?

Lua-based extension system

• Shortcodes
• Journal
• Formats
• Revealjs

nutshell shortcode by schochastics

Journal of Statistical Software (JSS)

nes-revealjs format by EmilHvitfeldt

attribution Revealjs Extension

Quarto also supports extensions. Quarto extensions are written in Lua, meaning that they are not language specific. So, you can use the same extension in a Jupyter file or a knitr file. Shortcodes let you add content, like fontawesome icons that you have seen in this presentation, or videos from YouTube. Filters let you add new markdown syntax for extended features. And formats are custom formats. There are built in extensions and then community built ones, if you search for Awesome Quarto, there are a list of them there.

Why Quarto?

webR

Run R in your Quarto documents thanks to the quarto-webr extension by James Joseph Balamuta.

Why Quarto?

Shinylive

With Shinylive, you can embed Shiny for Python applications into Quarto documents and run the entire application inside the user’s web browser.

Examples on the Shiny Website

Setting Up Quarto

Agenda

1. Introduction

2. Setting Up Quarto

3. Getting Started with Quarto

4. Creating Projects

5. Styling Quarto

6. Publishing Quarto

7. Conclusion

Quarto Installation

When you download the Quarto CLI, though, that’s all you need to run Quarto, so you can use just your Terminal or Command Line Interface for everything that we’ll explore, but you will need to install the engines if you’re going to run code with the CLI.

quarto.org

Quarto Tooling

Terminal

quarto render

Part of the multilingualism of Quarto is that you are not tied to one tool. Quarto is meant for collaboration either within data science teams or across data science teams. So if someone is familiar with Jupyter Lab, but someone else likes to work in RStudio, they can still work on the same Quarto documents without having to switch to one tool or the other.

For RStudio users, Quarto is bundled and preinstalled with v2022.07 and later. There are a lot of features that are built into RStudio for Quarto documents. We didn’t want to limit Quarto enhancements to just RStudio. VS Code has an extension so you can YAML completion and linting and other features for writing Quarto documents, and you can preview documents in Jupyter Notebooks and Jupyter Labs.

RStudio

To create a new document in RStudio, go to File > New File > Quarto Document:

A new document will be created with the following YAML. This document will be empty so it won’t be terribly interesting.

Working in RStudio

Rendering

Use the Render button () in the RStudio IDE to render the file and preview the output with a single click or keyboard shortcut (⇧⌘K).

Automatically render on save by checking the Render on Save option:

In RStudio, you can use the Render button to render the file, or take it through that process of convering to markdown, pandoc processing, etc. and preview the output with a single click. If you’re familiar with R Markdown, it is where the knit button would show for those document. If you prefer to automatically render whenever you save, you can check the Render on Save option on the editor toolbar. The preview will update whenever you re-render the document. Side-by-side preview works for both HTML and PDF outputs.

YAML Intelligence

YAML code completion is available for project files, YAML front matter, and executable cell options:

If you have incorrect YAML it will also be highlighted when documents are saved:

Quarto has YAML intelligence in RStudio and VS code. YAML intelligence means completion and diagnostics for errors, and its’ available for project files, YAML front matter, and executable cell options. This makes it easy to write YAML and see what has gone wrong rather than getting error messages that are really hard to decipher.

Working with the RStudio Visual Editor

RStudio has two options for editing documents: visual (on the left) and source (on the right). RStudio’s visual editor offers an WYSIWYM authoring experience for markdown. So formatting (e.g. bolding text) you can use the toolbar, a keyboard shortcut (⌘B), or the markdown construct (bold). The plain text source code underlying the document is written for you and you can view/edit it at any point by switching to source mode for editing. You can toggle back and forth these two modes by clicking on Source and Visual in the editor toolbar (or using the keyboard shortcut ⌘⇧ F4).

Getting Started with Quarto

Agenda

1. Introduction

2. Setting Up Quarto

3. Getting Started with Quarto

4. Creating Projects

5. Styling Quarto

6. Publishing Quarto

7. Conclusion

Contents of a Quarto Document

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

YAML

• “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, like title and author.

YAML

---
title: "Penguins, meet Quarto!"
format: html
editor: visual
---

Other 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.

YAML

---
title: "Penguins, meet Quarto!"
subtitle: "Intro to Quarto Exercise"
format: html
editor: visual
---

All YAML fields for HTML documents

Code Chunks

• Code chunks begin and end with three backticks (usually)
• Code chunks are identified with a programming language in between {}
• Can include optional chunk options, in YAML style, identified by #| at the beginning of the line

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.

Code Chunks

```{r, label="plot-penguins", warning=FALSE, echo=FALSE}
ggplot(penguins, 
       aes(x = flipper_length_mm, y = bill_length_mm)) +
  geom_point(aes(color = species, shape = species)) +
  scale_color_manual(values = c("darkorange","purple","cyan4")) +
  labs(
    title = "Flipper and bill length",
    subtitle = "Dimensions for penguins at Palmer Station LTER",
    x = "Flipper length (mm)", y = "Bill length (mm)",
    color = "Penguin species", shape = "Penguin species"
  ) +
  theme_minimal()
```

Code Chunks

```{r}
#| label: plot-penguins
#| warning: false
#| echo: false

ggplot(penguins, 
       aes(x = flipper_length_mm, y = bill_length_mm)) +
  geom_point(aes(color = species, shape = species)) +
  scale_color_manual(values = c("darkorange","purple","cyan4")) +
  labs(
    title = "Flipper and bill length",
    subtitle = "Dimensions for penguins at Palmer Station LTER",
    x = "Flipper length (mm)", y = "Bill length (mm)",
    color = "Penguin species", shape = "Penguin species"
  ) +
  theme_minimal()
```

Code Chunks

```{r}
#| label: plot-penguins
#| warning: false
#| echo: false
#| fig-alt: "Scatterplot with flipper length in millimeters on
#|  the x-axis, bill length in millimeters on the y-axis, colored
#|  by species, showing a slightly positive relationship with
#|  Chinstrap penguins having higher bill length but lower body
#|  mass, Adelie with low bill length and low body mass, and
#|  Gentoo with high body mass and high bill length."

ggplot(penguins, 
       aes(x = flipper_length_mm, y = bill_length_mm)) +
  geom_point(aes(color = species, shape = species)) +
  scale_color_manual(values = c("darkorange","purple","cyan4")) +
  labs(
    title = "Flipper and bill length",
    subtitle = "Dimensions for penguins at Palmer Station LTER",
    x = "Flipper length (mm)", y = "Bill length (mm)",
    color = "Penguin species", shape = "Penguin species"
  ) +
  theme_minimal()
```

The new hashpipe allows for consistency across Jupyter and knitr.

Code Chunks

In addition to rendering the complete document to view the results of code chunks you can also run each code chunk interactively in the RStudio editor by clicking the icon or keyboard shortcut (⇧⌘⏎). RStudio executes the code and displays the results either inline within your file or in the Console, depending on your preference.

Code Chunks

Cross referencing

```{r}
#| label: fig-penguins
#| warning: false

ggplot(penguins,
       aes(x = flipper_length_mm, y = bill_length_mm)) +
  geom_point(aes(color = species, shape = species)) +
  scale_color_manual(values = c("darkorange", "purple", "cyan4")) +
  labs(
    title = "Flipper and bill length",
    subtitle = "Dimensions for penguins at Palmer Station LTER",
    x = "Flipper length (mm)",
    y = "Bill length (mm)",
    color = "Penguin species",
    shape = "Penguin species"
  ) +
  theme_minimal()
```

See @fig-penguins.

Code Chunks

Cross referencing

Multiple Figures

Put two plots side by side:

```{r}
#| layout-ncol: 2
#| warning: false

ggplot(penguins, 
       aes(x = flipper_length_mm, y = bill_length_mm)) +
  geom_point(aes(color = species, shape = species))

ggplot(data = penguins, aes(x = flipper_length_mm)) +
  geom_histogram(aes(fill = species), 
                 alpha = 0.5, 
                 position = "identity")

```

Let’s add another plot to our chunk. Our goal is to display these plots side-by-side.

Multiple Figures

Put two plots side by side:

Multiple Figures

Put two plots side by side:

```{r}
#| layout: "[[30, 70]]"
#| warning: false

ggplot(penguins, 
       aes(x = flipper_length_mm, y = bill_length_mm)) +
  geom_point(aes(color = species, shape = species))

ggplot(data = penguins, aes(x = flipper_length_mm)) +
  geom_histogram(aes(fill = species), 
                 alpha = 0.5, 
                 position = "identity")

```

Code Options for All Chunks

Use the YAML to control options for all code chunks.

Hide all of the code and just show the output by specifying echo: false within the execute option in the YAML.

Echo

One chunk

```{r}
#| label: plot-penguins
#| echo: false

ggplot(penguins, 
       aes(x = flipper_length_mm, y = bill_length_mm)) +
  geom_point(aes(color = species, shape = species)) +
  scale_color_manual(values = c("darkorange","purple","cyan4")) +
  labs(
    title = "Flipper and bill length",
    subtitle = "Dimensions for penguins at Palmer Station LTER",
    x = "Flipper length (mm)", y = "Bill length (mm)",
    color = "Penguin species", shape = "Penguin species"
  ) +
  theme_minimal()
```

All chunks

```{yaml}
---
title: "Hello, Quarto!"
format: html
editor: visual
execute:
  echo: false
---
```

Code Options for All Chunks

Code Folding

```{yaml}
---
title: "Hello, Quarto!"
format:
  html:
    code-fold: true
---
```

Code Tools

```{yaml}
---
title: "Hello, Quarto!"
format:
  html:
    code-tools:
      source: https://quarto.org
---
```

Code Options for All Chunks

Code Linking

Needs downlit package

```{yaml}
---
title: "Hello, Quarto!"
format:
  html:
    code-link: true
---
```

You might want to fold it and allow readers to view it at their discretion. You can do this via the code-fold option. Remove the echo option we previously added and add the code-fold HTML format option.

Markdown Text

• 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.

Markdown Text

The `penguins` data from the [**palmerpenguins**](https://allisonhorst.github.io/palmerpenguins "palmerpenguins R package") package contains size measurements for `r nrow(penguins)` penguins from three species observed on three islands in the Palmer Archipelago, Antarctica.

The penguins data from the palmerpenguins package contains size measurements for 344 penguins from three species observed on three islands in the Palmer Archipelago, Antarctica.

If using the visual editor, you won’t need to learn much markdown syntax for authoring your document as you can use the menus and shortcuts to add a header, bold text, insert a table, etc. If using the source editor, you can achieve these with markdown expressions like ##, bold, etc.

Markdown Text

Formatting

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

Markdown Text

Images and Links

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


Photo by Cornelius Ventures on Unsplash

Markdown Text

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

Markdown Text

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

Quarto guide for Markdown basics

Quarto Authoring

Diagrams

Quarto has native support for embedding Mermaid and Graphviz 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.

Quarto Authoring

Equations

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

\[E = mc^{2}\]

Quarto Authoring

Title Banners

HTML pages rendered with Quarto include a formatted title banner at the start of the article.

Title Banners

---
title: "Penguins, meet Quarto!"
format: html
editor: visual
---

Toggle on…

Title Banners

---
title: "Penguins, meet Quarto!"
title-block-banner: true
format: html
editor: visual
---

Title Banners

Use a color…

---
title: "Penguins, meet Quarto!"
title-block-banner: "#FDA172"
format: html
editor: visual
---

Title Banners

Or a photo!

---
title: "Penguins, meet Quarto!"
title-block-banner: "banner-image.jpg"
format: html
editor: visual
---

All title block metadata

Divs and Spans

You can add classes, attributes, and other identifiers to content using Divs and Spans.

Divs

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

Spans

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

Pandoc and therefore Quarto can parse fenced Div blocks, which lets you modify the structure of your documents. You can add classes, attributes, and other identifiers to regions of content using Divs and Spans. You can think of divs as HTML divs but can be applied in PDFs or other formats like Word. Here is an example of a call out, which calls out special content for readers and you may have seen them in books or papers. Quarto has this for all different formats using Divs.

Divs

• ::: - Div start and end
• #id - label
• .class - behavior
• attribute=value - customization

Divs

Callout Blocks

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

Callout Blocks

::: {#call1 .callout-note appearance="simple"}

## Pay Attention

Using callouts is an effective way to highlight content that your reader give special consideration or attention.

:::

Pay Attention

Using callouts is an effective way to highlight content that your reader give special consideration or attention.

Divs

Callout Blocks

Warning

.callout-warning

Caution

.callout-caution

Important

.callout-important

Divs

Multiple columns

```{markdown}
::: {layout-ncol=2}

![](penguin.jpg)

Photo by <a href="https://unsplash.com/@corneliusventures?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Cornelius Ventures</a> on <a href="https://unsplash.com/s/photos/penguin?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Unsplash</a>
:::
```

. . .

Photo by Cornelius Ventures on Unsplash

Divs

Multiple columns

```{markdown}
::: {layout="[[1,1], [1]]"}
![penguin 1](penguin.jpg)

![penguin 2](penguin.jpg)

![penguin 3](penguin.jpg)
:::
```

penguin 1

penguin 2

penguin 3

Divs

Tabsets

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

`library(dplyr)`

## Python

`import pandas as pd`
:::
```

• R
• Python

library(dplyr)

import pandas as pd

Spans

• [] and {} for span start and end
• .class - behavior
• key="val" - customization

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.

Spans

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

This is text that is red.

Spans

```{markdown}
![](penguin.jpg){fig-alt="A photo of a penguin jumping"}
```

```{markdown}
![](penguin.jpg){fig-alt="A photo of a penguin jumping" width=100}
```

Other formats

You can create Revealjs presentations using the revealjs format.

```{yaml}
---
title: "Penguins, meet Quarto!"
format: revealjs
editor: visual
---
```

Revealjs

Code Line Numbers

```{r}
#| echo: true
#| eval: FALSE
#| code-line-numbers: 3-4

ggplot(penguins, 
       aes(x = flipper_length_mm, y = bill_length_mm)) +
  geom_point(aes(color = species, shape = species)) +
  scale_color_manual(values = c("darkorange","purple","cyan4")) 
```

ggplot(penguins, 
       aes(x = flipper_length_mm, y = bill_length_mm)) +
  geom_point(aes(color = species, shape = species)) +
  scale_color_manual(values = c("darkorange","purple","cyan4")) 

Most of the core capabilities of Quarto HTML Code Blocks are available for Reveal slides, including code folding, code copy, and the ability to pick a custom syntax highlighting theme. Revealjs also has some functionality not available in documents, such as code-line-highlighting, which lets you highlight specific lines of code output or highlight distinct lines over a progression of steps.

Revealjs

Incremental

```{markdown}
::: {.incremental}
- Adelie
- Chinstrap
- Gentoo
:::
```

• Adelie
• Chinstrap
• Gentoo

All about revealjs in Quarto

By default number and bullet lists within slides are displayed all at once. You can override this globally using the incremental option.

Creating Projects

Agenda

1. Introduction

2. Setting Up Quarto

3. Getting Started with Quarto

4. Creating Projects

5. Styling Quarto

6. Publishing Quarto

7. Conclusion

Quarto Projects

Quarto projects are directories that provide:

• A way to render all or some of the files in a directory with a single command (e.g. quarto render myproject).
• A way to share YAML configuration across multiple documents.
• The ability to redirect output artifacts to another directory.
• The ability to freeze rendered output (i.e. don’t re-execute documents unless they have changed).

Quarto Projects

Setup

```{yaml}
project:
  output-dir: _output

toc: true
number-sections: true
bibliography: references.bib  
  
format:
  html:
    css: styles.css
    html-math-method: katex
  pdf:
    documentclass: report
    margin-left: 30mm
    margin-right: 30mm
```

Within a Quarto project, you can render all the files at once or specify specific ones to render. So, say you have a website and you want to change the theme throughout, rather than rendering individual pages you can do that all with one command in a project. Quarto projects also include a _quarto.yml configuration file so that every document in the project inherits the metadata in that file. So, if you think about a blog, you probably want all your posts to have the same theme. If you use the Quarto command for making a new blog, it will automatically be a project, and you can configure the theme for all pages in the _quarto.yml file.

Quarto Projects

Freeze

```{yaml}
execute:
  freeze: true  # never re-render during project render
```

```{yaml}
execute:
  freeze: auto  # re-render only when source changes
```

Rendering a bunch of files can be quite time consuming depending on the computations required. The freeze option specifies if computational documents should never be re-rendered during a global project render, or only be re-rendered when their source file changes. Freeze can used when you have either a large number of collaborators or many computational documents created over a long period of time. In these cases, it can be challenging to fully re-execute every document when you render the site. This could be because some documents have environment-specific requirements or one of your teammates wrote something in Python, which you don’t have installed. Using freeze ensures that you can always reproducibly render your site.

Styling Quarto

Agenda

1. Introduction

2. Setting Up Quarto

3. Getting Started with Quarto

4. Creating Projects

5. Styling Quarto

6. Publishing Quarto

7. Conclusion

HTML Theming

Quarto includes 25 themes from the Bootswatch project:

• default
• cerulean
• cosmo
• cyborg
• darkly
• flatly
• journal
• litera
• lumen
• lux
• materia
• minty
• morph
• pulse
• quartz
• sandstone
• simplex
• sketchy
• slate
• solar
• spacelab
• superhero
• united
• vapor
• yeti
• zephyr

HTML Theming

Use these themes under the theme option in the YAML:

```{yaml}
format:
  html:
    theme: flatly
```

HTML Theming

You can do extensive additional customization using SASS theme files.

• Bootstrap defines over 1,400 variables that control fonts, colors, padding, borders, and much more!

```{css}
/*-- scss:defaults --*/

$body-bg: #CDEEFD;

/*-- scss:rules --*/
h1, h2, h3, h4, h5, h6 {
  text-shadow: -1px -1px 0 rgba(0, 0, 0, .3);
}
```

HTML Theming

Provide the custom theme under theme:

```{yaml}
theme:
  - flatly
  - custom.scss
```

HTML Theming

Quarto also allows you to use a dark and light theme.

```{yaml}
theme:
  light: flatly
  dark: darkly
```

Publishing Quarto

Agenda

1. Introduction

2. Setting Up Quarto

3. Getting Started with Quarto

4. Creating Projects

5. Styling Quarto

6. Publishing Quarto

7. Conclusion

Publishing options

Since content rendered with Quarto uses standard formats (HTML, PDFs, MS Word, etc.) it can be published anywhere.

Some options:

• Quarto Pub
• GitHub Pages
• RStudio Connect
• Netlify

There’s an integrated quarto publish command that lets you publish in a bunch of places.

Quarto Pub

Quarto Pub is a free publishing service for content created with Quarto.

• Must be publicly available
• Cannot be larger than 100 MB
• Has a soft limit of 10 GB a month

Terminal

quarto publish quarto-pub hello.qmd

Terminal

# token created at https://quartopub.com/profile/
export QUARTO_PUB_AUTH_TOKEN="qpa_k4yWKEmlu5wkvx173Ls"

# publish to quarto-pub site specified within _publish.yml
quarto publish quarto-pub

Conclusion

Agenda

1. Introduction

2. Setting Up Quarto

3. Getting Started with Quarto

4. Creating Projects

5. Styling Quarto

6. Publishing Quarto

7. Conclusion

Thank you!

I hope that you enjoyed this intro to Quarto!

• Keep in touch on Twitter: ivelasq3.
• Read the Quarto documentation.
• Check out Awesome Quarto.

Acknowledgements

• Quarto questions by Marc Dotson
• Improvements in text processing using textrecipes by Emil Hvitfeldt