Quarto

An open-source tool for scientific publishing

Last Time

1. Two more verbs: distinct() and count().
2. Chain operations using the pipe operator (|>).
3. Debug a pipeline by breaking the pipe and inspecting each stage.
4. group_by() puts rows into groups for downstream verbs.

Key Ideas for Today

1. A Quarto document mixes prose and code in a single .qmd file.
2. Format text using Markdown syntax.
3. Embed code cells with options to control evaluation and display.
4. Configure the metadata (YAML) to set its format and options.

Concept Acquisition

1. Literate programming interleaves natural-language explanation with source code, so a single document produces both the report and the analysis behind it.
2. A Quarto document keeps prose, code, and metadata in separate regions of one file.
3. Source is kept separate from output: one .qmd can be rendered to many formats (HTML, PDF, Word, slides).
4. Positron brings the file system, shell, R/Python, git, and Quarto together in one environment.

Tool Acquisition

1. quarto render and quarto preview at the command line.
2. Markdown syntax for headers, italics, bold, ordered and unordered lists, footnotes, and images.
3. Code cell syntax: opening and closing fences, language, and #| cell options (eval, echo, message, warning, figure size), plus displaying tables.
4. YAML metadata: opening and closing fences and common format values.
5. The Quarto Guide and Quarto Reference as documentation for finding new options.

Concept Application

1. Open hello-penguins.qmd in Positron and work through its Markdown, code cells, and metadata, re-rendering along the way.
2. Use the Quarto documentation to change the HTML theme, add a table of contents, and switch to typst or pdf.
3. Convert the document to revealjs slides, add a slide, and change the transition style (bonus: install and use a Quarto extension theme).

Quarto at the Command Line

Motivation: our analyses are getting more complicated. Just providing code is a very insufficient way to communicate what the code is doing. Comments help but are messy.

Start with a blackboard definition:

Literate programming is a programming paradigm introduced in 1984 by Donald Knuth in which a computer program is given as an explanation of how it works in a natural language, such as English, interspersed (embedded) with snippets of macros and traditional source code, from which compilable source code can be generated

The Plan

Together we will:

1. Create a new Quarto document.
2. Render it and preview it.
3. Add text with Markdown.
4. Add code cells.
5. Add metadata.

Ask students to just watch, not follow along.

Open terminal and go into dir on desktop. Run echo “hello world” > hello.qmd then open that file with a text editor and go back and forth between the terminal and the editor to

quarto render

Runs all of the code in a .qmd file, formats the text, and renders into a formatted document.

quarto render mydoc.qmd

quarto preview

Renders a .qmd file and opens a live preview that automatically re-renders and refreshes whenever the file is saved.

quarto preview mydoc.qmd

Guess the Metaphor

A Quarto doc is like a spellbook: the incantations (code) are written out next to the explanations of what they do and why (prose), and nothing happens until you cast it.

When you render, every spell runs in order and its effects (tables, figures, results) appear on the page, so anyone with the book can cast the same spells and get the same results.

What is Quarto?

boardwork

Draw diagram with a qmd file on the left with three sections, text, code, and yaml. Right arrow from that to a circle (the pandoc AST but don’t call it that) then arrows from the circle to three files: html, pdf, and docx.

Below, write:

Advantages:

• Separation of code and text but bundled in the same file
• Separation of source and output
• All while Literate Programming

Quarto in Positron

Our tools so far:

• File Systems
• Unix Shell
• R (or Python)
• git
• quarto

boardwork

Draw diagram of positron as putting the file system, the terminal, R/Py, git, and quarto all in the same place.

Making a Quarto Doc

Hello Penguins!

Please download hello-penguins.qmd from Ed, put it in a directory on your desktop, then open it as a folder in Positron.

Markdown

• Headers
• Italics
• Bold
• Unorderd list
• Ordered List
• Footnote
• Image

Code Cells

• Begin / End
• Language
• Cell options behind |#
  • Evaluate code
  • Show code
  • Show message
  • Show warnings
  • Figure size
• Displaying tables

Metadata

• Begin / End
• Common formats
• YAML

Your Turn I

Using the Quarto Guide https://quarto.org/docs/guide/ and the Quarto Reference (https://quarto.org/docs/reference/), do each of the following and then re-render your document.

1. Change the theme of your HTML file
2. Add a table of contents
3. Change format to either typst or pdf

03:00

Your Turn II

Using the Quarto Guide https://quarto.org/docs/guide/ and the Quarto Reference (https://quarto.org/docs/reference/), do each of the following and then re-render your document.

1. Change format to revealjs
2. Add a new slide with a bulleted list of your three favorite foods
3. Change the transition style
4. Bonus: Run quarto add schochastics/quarto-blackboard-theme at the terminal (say yes to everything) then change format to blackboard-revealjs.

04:00

Key Ideas for Today

1. A Quarto document mixes prose and code in a single .qmd file.
2. Format text using Markdown syntax.
3. Embed code cells with options to control evaluation and display.
4. Configure the metadata (YAML) to set its format and options.

For Next Time

1. Project Studio 2 next week!