Documents: YAML + Markdown Basics

Intro Quarto @ Cascadia R Conf

Charlotte Wickham

Posit, PBC

Anatomy of a Quarto document

Components

1. Metadata: YAML

2. Text: Markdown

3. Code: Executed via knitr or jupyter

Weave it all together, and you have beautiful, powerful, and useful outputs!

Metadata

YAML

“Yet Another Markup Language” or “YAML Ain’t Markup Language” is used to provide document level metadata …

… in key-value pairs,

… that can nest,

… are fussy about indentation,

… and are kept between ---.

---
key: value
---

Example: Output options

---
format: something
---

---
format: html
---

---
format: pdf
---

---
format: revealjs
---

Example: Indented nesting

Indentation matters!

---
format: 
  html:
    toc: true
    code-fold: true
---

Fussing with YAML (invalid)

• Invalid: No space after :

---
format:html
---

• Invalid: Read as missing

---
format:
html
---

• Valid, but needs next object

---
format: 
  html:
---

Fussing with YAML (valid)

There are multiple ways of formatting valid YAML:

• Valid: There’s a space after :

format: html

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

format:
  html

• Valid: format: html with additional options made with proper indentation

format: 
  html:
    toc: true

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

Quarto linting

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

• Open hello-penguins.qmd in RStudio.
• Try Ctrl + space to see the available YAML options.
• Try out the tab-completion of any options that sound interesting.
• You can use the HTML reference as needed.
• Share one you tried with your neighbor.

05:00

List of valid YAML fields

• Many YAML fields are common across various outputs

• But also each output type has its own set of valid YAML fields and options

• Definitive list: quarto.org/docs/reference/formats/html

Text

https://quarto.org/docs/authoring/markdown-basics.html

Text Formatting

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

Headings

Markdown Syntax	Output
# Header 1	Header 1
## Header 2	Header 2
### Header 3	Header 3
#### Header 4	Header 4
##### Header 5	Header 5
###### Header 6	Header 6

Links

There are several types of “links” or hyperlinks.

Markdown

You can embed [named hyperlinks](https://quarto.org/),
direct urls like <https://quarto.org/>, and links to 
[other places](#quarto-anatomy) in 
the document. The syntax is similar for embedding an
inline image: ![Penguins playing with ball](images/penguins-quarto-ball.png).

Output

You can embed named hyperlinks, direct urls like https://quarto.org/, and links to other places in the document. The syntax is similar for embedding an inline image: .

Markdown figures

![Penguins playing with a Quarto ball](images/penguins-quarto-ball.png)

Penguins playing with a Quarto ball

Markdown figures with options

![](images/penguins-quarto-ball.png){fig-align="left" width=250}

![](images/penguins-quarto-ball.png){fig-align="right" width=250 fig-alt="Illustration of two penguins playing with a Quarto ball."}

Lists

Unordered list:

Markdown:

-   unordered list         
    -   sub-item 1         
    -   sub-item 1         
        -   sub-sub-item 1 

Output

• unordered list
  • sub-item 1
    
  • sub-item 1
    • sub-sub-item 1

Ordered list:

Markdown:

1. ordered list            
2. item 2                  
   i. sub-item 1          
      A.  sub-sub-item 1

Output

1. ordered list
   
2. item 2
   1. sub-item 1
      1. sub-sub-item 1

Quotes

Markdown:

> Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do. 
> - Donald Knuth, Literate Programming

Output:

Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do. - Donald Knuth, Literate Programming

“Literate Programming”, The Computer Journal 27 (1984), p. 97. (Reprinted in Literate Programming, 1992, p. 99.) Literate Programming (1984)

Your turn

• Open markdown-syntax.qmd in RStudio.
• Follow the instructions in the document for how to modify it.

05:00