Extending Quarto

Lecture 17

Dr. Benjamin Soltoff

Cornell University
INFO 3312/5312 - Spring 2024

March 26, 2024

Announcements

Announcements

• Homework 05
• Project 02 proposals

Agenda

Review

• Identify a reproducible Quarto workflow
• Define major components of Quarto documents
• Customize individual Quarto documents using code chunk options and YAML header

New

• Extend Quarto to multi-file projects/websites
• Examine structure of Quarto blog
• Publish Quarto documents to the web

Quarto

Quarto basics

---
title: Gun deaths
author: Your name
date: today
format: html
---

```{r}
#| label: setup
#| include: false
library(tidyverse)
library(rcis)

youth <- gun_deaths |>
  filter(age <= 65)
```

# Gun deaths by age

We have data about `r nrow(gun_deaths)` individuals killed by guns. Only `r nrow(gun_deaths) - nrow(youth)` are older than 65. The distribution of the remainder is shown below:

```{r}
#| label: youth-dist
#| echo: false
ggplot(data = youth, mapping = aes(x = age)) + 
  geom_freqpoly(binwidth = 1)
```

# Gun deaths by race

```{r}
#| label: race-dist
youth |>
  mutate(race = fct_infreq(race) |> fct_rev()) |>
  ggplot(mapping = aes(y = race)) +
  geom_bar() +
  labs(y = "Victim race")
```

Major components

1. A YAML header surrounded by ---s
2. Chunks of code surounded by ```
3. Text mixed with simple text formatting using the Markdown syntax

Quarto code chunks

Rendering process

Artwork from “Hello, Quarto” keynote by Julia Lowndes and Mine Çetinkaya-Rundel, presented at RStudio Conference 2022. Illustrated by Allison Horst.

Rendering process

Artwork from “Hello, Quarto” keynote by Julia Lowndes and Mine Çetinkaya-Rundel, presented at RStudio Conference 2022. Illustrated by Allison Horst.

Code chunks

```{r}
#| label: youth-dist
#| message: false
#| warning: false

# code goes here
```

• Naming code chunks
• Code chunk options
• eval: true
• include: true
• echo: true
• message: true or warning: true
• cache: true

Inline code

We have data about `r nrow(gun_deaths)` individuals killed by guns.

Only `r nrow(gun_deaths) - nrow(youth)` are older than 65. The distribution of the remainder is shown below:

We have data about 100798 individuals killed by guns.

Only 15687 are older than 65.

YAML header

YAML header

---
title: Gun deaths
author: Benjamin Soltoff
date: today
format: html
---

• YAML Ain’t Markup Language
• Standardized format for storing hierarchical data in a human-readable syntax
• Defines how quarto renders your .qmd file

HTML document

---
title: Gun deaths
author: Benjamin Soltoff
date: today
format: html
---

Table of contents

---
title: Gun deaths
author: Benjamin Soltoff
date: today
format:
  html:
    toc: true
    toc-depth: 2
---

Appearance and style

---
title: Gun deaths
author: Benjamin Soltoff
date: today
format:
  html:
    theme: superhero
    highlight-style: github
---

Global options

---
title: "My Document"
format:
  html:
    fig-width: 7
execute:
  echo: true
  message: false
knitr:
  opts_chunk: 
    dev: ragg_png
---

• Default document-level options
• Some options are set with format
• Some options are set with execute
• Some options are set by knitr/jupyter

PDF document

---
title: Gun deaths
author: Benjamin Soltoff
date: today
format: pdf
---

Presentation

---
title: Gun deaths
author: Benjamin Soltoff
date: today
format: revealjs
---

Quarto supports multiple presentation formats

• revealjs (HTML)
• pptx (PowerPoint)
• beamer (\(\LaTeX\)/PDF)

Websites using Quarto

Websites

• Websites are essentially format: html + a Quarto Project
• Website is different than format: html in that it has multiple pages
• Website is our first exploration into Quarto Projects
  • Similar to R Projects, but for Quarto!
  • You used them for project 01

Why not WordPress, Tumblr, Medium.com, Blogger.com, etc?¹

• No Quarto support (even math support is often nonexistent or awkward)

• Huge benefits of static websites compared to dynamic websites

• All static files, no PHP or databases, no login/password, work everywhere (even offline)

• Typically fast to visit (no computation needed on the server side), and easy to speed up via CDN

1. From Yihui: https://slides.yihui.name/2017-rmarkdown-UNL-Yihui-Xie.html#36

RStudio > New Project > New Quarto Blog

Navigation & Structure

File	Description
_quarto.yml	Quarto project file.
index.qmd	Blog home page.
about.qmd	Blog about page.
posts/	Directory containing posts
posts/_metadata.yml	Shared options for posts
styles.css	Custom CSS for website

Create a blog

• A blog is a website with specific “opinions” already made
• Includes a listing automatically from posts directory
• Can build custom listings in several ways

Core blog workflow

• Create a new folder under /posts - this folder will be the “slug” URL (like bensoltoff.com/my-new-post/)
• Create a new index.qmd within the new folder

Application exercise

ae-14

• Go to the course GitHub org and find your ae-14 (repo name will be suffixed with your GitHub name).
• Clone the repo in RStudio Workbench, open the Quarto document in the repo, and follow along and complete the exercises.
• Render, commit, and push your edits by the AE deadline – end of tomorrow

Your Turn

• Explore the repo directories and file structure
• What types of files are stored in the repo? Where can you find source code files? Output files?

Rendering posts

Rendering posts

• On a specific post, Render with RStudio > Render
• Build tab > Render/Preview Website

These will preview the entire website

When you render the website, it will re-execute code in older posts. Not ideal in many situations!

Your Turn

• Let’s render the index.qmd together!
• Now, let’s try Build > Render Website
• Stage/commit/push all changes to GitHub

Freeze

You can use the freeze option to denote that computational documents should never be re-rendered during a global project render, or alternatively only be re-rendered when their source file changes

execute:
  freeze: true  # never re-render during project render

execute:
  freeze: auto  # re-render only when source changes

freeze: true is typically added to a _metadata.yml file within a specific directory, affecting all files in that directory.

In the case of a blog - the _metadata.yml is saved at the root of the posts directory. You can have it only within specific subdirectories for more complex sites.

Cache

Cache on the other hand, stores the results of computations for a specific file.

Note that cache invalidation is triggered by changes in chunk source code (or other cache attributes you’ve defined).

execute:
  cache: true

I typically use cache throughout various types of outputs when I have computationally expensive chunks.

Your Turn

• Render index.qmd in the project directory and note the items that are built

• Explore the _freeze directory

• Marvel at the “beautiful” JSON - it’s not for you, it’s for the machine

Themes

https://quarto.org/docs/websites/website-blog.html#themes

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

To change theme, modify the bottom of your website’s _quarto.yml

format:
  html:
    theme: cosmo

Themes

Your Turn

• Open _quarto.yml and change the theme to one of the support Bootswatch themes
• Modify posts/gun-deaths/index.qmd in some way
• Render the website!

Adding an About page

Adding an About page

title: "Benjamin Soltoff"
about:
  template: jolla
  image: profile.png
  links:
    - icon: twitter
      text: twitter
      href: https://twitter.com/soltoffbc
    - icon: github
      text: Github
      href: https://github.com/bensoltoff
    - icon: building
      text: Faculty page
      href: https://infosci.cornell.edu/content/soltoff

About page templates

about:
  template: trestles

• jolla
• trestles
• solana
• marquee
• broadside

Your Turn

• Open your about page (about.qmd)
• Change some of the details, add more details and choose a specific template (jolla, trestles, solana, marquee, broadside)
• Render it!

Website organization

Landing page

• The landing page for your website defaults to the blog/listings page
• your-proj/index.qmd becomes your “home page”

• If you want your “About Me” page to be the landing page, rename your index.qmd -> blog.qmd and about.qmd -> index.qmd

• Re-structuring your website also requires modifying your _quarto.yml

website:
  title: "My blog name"
  site-url: "https://MyBlogSiteUrl.com"
  navbar:
    right:
     - blog.qmd
     - icon: twitter
       href: "https://twitter.com/my_user_name"

Example: https://www.ericekholm.com/posts/demo-quarto-site/

Listings

Listings

Type	Description
default	A blog style list of items.
table	A table of listings.
grid	A grid of listing cards.

Listings

• Default
• Grid
• Table

By default, listings will appear in full width rows that display the item’s metadata (author and date), title, description, and image.

Grid style listings display a card for each item.

The table listing style provides a traditional tabular layout.

Your Turn

• Open your existing Quarto blog from before
• Let’s change the listing type of our blog - change from default to grid
• Re-render the index.qmd

Publishing

Publishing

Destination	Description
GitHub Pages	Publish content based on source code managed within a GitHub repository. Use GitHub Pages when the source code for your document or site is hosted on GitHub.
RStudio Connect	Publishing platform for secure sharing of data products within an organization. Use RStudio Connect when you want to publish content within an organization rather than on the public internet.
Netlify	Professional web publishing platform. Use Netlify when you want support for custom domains, authentication, previewing branches, and other more advanced capabilities.
Other Services	Content rendered with Quarto uses standard formats (HTML, PDFs, MS Word, etc.) that can be published anywhere. Use this if one of the methods above don’t meet your requirements.

Publishing

Static Only

• quarto R package: quarto::quarto_publish_???()

Code

• Evaluate R/Python code and render on a schedule

• RStudio Connect

• rsconnect::deployDoc(quarto = "path/to/quarto")

  • rsconnect::deployDoc(quarto = quarto::quarto_path())

Static Publish

• quarto::quarto_publish_???()

  • quarto_publish_site(server = "rstudioconnect.example.com")
  • quarto_publish_doc(server = "rpubs.com")
  • quarto_publish_app(server = "shinyapps.io")

Netlify

• Cheat code: Netlify drop

GitHub Pages

• Render contents locally with the “Build Website” button
• Stage/commit/push the rendered files to GitHub – site built automatically

Check out your site at

https://pages.github.coecis.cornell.edu/info3312-sp24/ae-14-NETID

Websites

Similar to blog, but less of a focus on listing/posts and more focus on individual pages and overall navigation.

Quarto Project

• https://quarto.org/docs/projects/quarto-projects.html

When you create a project, a _quarto.yml config file is created. Here is an example of what the _quarto.yml looks like:

project:
  output-dir: _output

toc: true
number-sections: true
bibliography: references.bib  
  
format:
  html:
    css: styles.css

Quarto Projects

• Minimal project has at least 1x file and 1x _quarto.yml
• A project is a directory (and can have sub-directories)

A typical project is used to:

• Aggregate content (website/blog/book)
  
• Share metadata (YAML config) across multiple files
  
• Render an entire directory together or redirect output to another directory
  
• Freeze computation across a project or team

• Our course website

Wrap up

Wrap up

• Quarto is a versatile tool for creating documents, websites, and more
• Can be used for single or multiple-document projects
• Generates static websites incorporating programmatic content (R, Python, etc.)
• Websites can be published directly through GitHub or alternative providers

Acknowledgements

• Website content adapted from Getting Started with Quarto by Tom Mock and licensed under a Creative Commons Attribution 4.0 International License.