Introduction to reproducible documents with Quarto

LAVA meeting Nov 29, 2022

Stephan König

stephan.koenig@ubc.ca

Skylight, University of British Columbia

Advantages

• Makes content and structure of a document explicit
• Enables flexible output to many formats
• Facilitates collaboration and reproducible workflows

Source and Output in a single file

Source and Output in a single file

Source and Output are separate files

Source

Output

Markup

Markup is specifically used to label parts of the document for what they are, rather than how they should be processed.

— Wikipedia

The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. […] To this end, Markdown’s syntax is comprised entirely of punctuation characters, which punctuation characters have been carefully chosen so as to look like what they mean. E.g., asterisks around a word actually look like *emphasis*.

— John Gruber

Your Turn: Markdown

• Open https://commonmark.org/help/tutorial/
• Explore Markdown syntax
• Check out the Code formatting section

Quarto

• Is an open-source command line interface tool for scientific and technical publishing
• Provides a comprehensive set of feature out of the box
• Uses as source plain text formats (.qmd, .rmd, .md) or mixed formats (.ipynb/Jupyter notebook)
• Creates outputs including PDF, Word, HTML reports, books, websites, presentations & more
• Prevents fragmentation by interleaving of descriptive text, code and its outputs

How Quarto works

Pandoc is a Rosetta Stone

Your Turn: Posit Cloud

• Create free Posit Cloud account https://posit.cloud/plans/free
• Open https://posit.cloud/content/4332583
• OR: Open your local install of RStudio

Basic structure of Quarto document

---
title: "Untitled"
format: html
---

## 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}
1 + 1
```

• Metadata as YAML
• Text
• Code

Your Turn

• Use as reference: https://quarto.org/docs/reference/formats/html.html
• Edit title and add your name as the author
• Change theme to sketchy
• Add TOC
• Create two sections, one with something you learned and your favourite thing
• Render it with Posit Cloud button

Resources

• Daring Fireball: Markdown
• Interactive Commonmark Markdown tutorial
• Quarto documentation
• Get started with Quarto Workshop with introductory video and material