Document Formats

Session 1: Getting to know Quarto

Cynthia Huang

Tuesday, July 18, 2023

Anatomy of a Quarto Document

Basic Components

---
title: "Anatomy of a Quarto Document"
---

## R

```{r}
head(mtcars)
```

## STATA

```stata
version 13
use censas
tabulate region
summarize marriage_rate divorce_rate median_age if state!="Nevada"
```

The script above is from the [Section 16.1](https://www.stata.com/manuals13/u16.pdf) of the *Stata 13 Manual*

• Metadata: an (optional) YAML header
• Content: markdown syntax
• Code: executed by knitr (R) or jupyter (python)

YAML Metadata

• “Yet Another Markup Language” or “YAML Ain’t Markup Language”

key: value

• Control whole document or project options and metadata
• If YAML header is missing, Quarto defaults apply.
• Available options differ by format: HTML, PDF, Websites

Markdown Content

not covered in detail, but we will briefly look at some features

• Simple text formatting:
  • # Heading
  • _italics_, **bold**, `code`
  • [linked phrase](http://example.com)
• Content features:
  • Figures
  • Tables
  • References

Code Blocks

not covered beyond displaying code

• Chunks of code between ```s.
• Syntax highlighting for ~140 Languages: ```stata
• Executable R/python/Julia code starts with: ```{r}

Quarto Formats

One important thing that YAML metadata controls are format options. YAML will also be important for websites

Many Quarto formats & features

Feature	Quarto
Basic Formats	html, pdf, docx
Cross References	Quarto Crossrefs
Websites & Blogs	Quarto Websites Quarto Blogs
Journal Articles	Journal Articles
Advanced Layout	Quarto Article Layout

Feature	Quarto
Beamer	beamer
PowerPoint	pptx
HTML Slides	revealjs
Books	Quarto Books
Interactivity	Quarto Interactive Documents
Dashboards	Coming soon!

Our Turn: Quarto Formats

~10 mins show my_first_doc.qmd - what format, where to, whole doc features - render options (YAML) - html then pdf - YAML features - title - keep tex - render HTML again – show multi-format

• Open my_first_doc.qmd again in RStudio.
• What is the default rendering format?
• Add PDF format options and keep the intermediate .tex file:

---
format:
  latex: default
  html: default
---

• Render the document as a PDF.
• Extension: Can you preview the HTML again?

[HINT: Use quarto preview in the Terminal]

YAML

YAML options

Indentation matters!

---
format: 
  html:
    toc: true
    toc-depth: 2
---

A sneak preview of YAML for websites:

_quarto.yml

---
project:
  type: website
  output-dir: _site
---

Why YAML?

To avoid manually typing out all the options, every time when rendering via the CLI:

quarto render document.qmd --to html

quarto render document.qmd --to html -M code-fold:true

quarto render document.qmd --to html -M code-fold:true -P alpha:0.2 -P ratio:0.3

YAML validation

• Invalid: No space after :

---
format:html
---

• Invalid: Read as missing

---
format:
html
---

• Valid, but needs next object

---
format: 
  html:
---

YAML validation

There are multiple ways of formatting valid YAML:

• Valid: There’s a space after :

format: html

• Valid: There are 2 spaces a new line and no trailing :

format:
  html

• Valid: format: html with selections made with proper indentation

format: 
  html:
    toc: true

Quarto linting

how to validate all these options?

Lint, or a linter, is a static code analysis tool used to flag programming errors, bugs, stylistic errors and suspicious constructs.

Source: https://en.wikipedia.org/wiki/Lint_(software)

Quarto YAML Intelligence

RStudio + VSCode provide rich tab-completion - start a word and tab to complete, or Ctrl + space to see all available options.

Your turn: Quarto YAML Intelligence

• Open my_first_doc.qmd again in RStudio.
• Try Ctrl + space in the YAML header to see the available YAML options.
• Try out the tab-completion to add:
  • a table of contents and,
  • number the sections.

See PDF Format Guide if needed.

05:00

More YAML? More Features!

HTML Guide

HTML Full Reference

More YAML? More Features!

PDF Guide

PDF Full Reference