Part 2: Quarto Introduction

OCTRI-BERD Workshop July 2025

Jessica Minnier, Meike Niederhausen

OHSU-PSU School of Public Health

2025-07-17

Outline

• Create & render a Quarto file
• 3 types of Quarto content:

1. Text editing
   • Formatting text; visual editor
   • Headers
   • Lists
   • Hyperlinks
   • Images
   • Tabsets
   • Callout Blocks
   • Tables
   • Equations with LaTeX

2. Code chunks & options
   • Creating and running code chunks
   • Options: show vs. hide code & output
   • Local vs global code chunk options
3. YAML metadata
   • Title, subtitle, author, date, institution
   • Change output file type (html, slides, Word, etc.)
   • Table of contents
   • Code folding

Basic Quarto example

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

1. Create a Quarto file (.qmd)

Two options:

1. click on File \(\rightarrow\) New File \(\rightarrow\) Quarto Document…\(\rightarrow\) OK,
2. or in upper left corner of RStudio click on \(\rightarrow\)

Pop-up window selections:

• Enter a title and your name
• Select HTML output format (default)
• Engine: select Knitr
• Editor: Select Use visual markdown editor
• Click Create

2. Create a Quarto file (.qmd)

• After clicking on Create, you should then see the following in your editor window:

3. Save the Quarto file (.qmd)

• Save the file by
  • selecting File -> Save,
  • or clicking on (towards the left above the scripting window),
  • or keyboard shortcut
    • PC: Ctrl + s
    • Mac: Command + s
• You will need to specify
  • a filename to save the file as
    • ALWAYS use .qmd as the filename extension for Quarto files
  • the folder to save the file in

4. Create (render) html file

We create the html file by rendering the .qmd file.

Two options:

1. Click on the Render icon at the top of the editor window,

2. Or use keyboard shortcuts
   • Mac: Command+Shift+K
   • PC: Ctrl+Shift+K

• A new window will open with the html output.
• You will now see both .qmd and .html files in the folder where you saved the .qmd file.

Note

• The template .qmd file that RStudio creates will render to an html file by default.
• The output format can be changed to create a Word doc, pdf, slides, etc.

.qmd file vs. its html output

.qmd file

html output

Download .qmd file with code from slides

If you want to run the code in the slides in your own RStudio, we recommend downloading a qmd file with the code.

3 types of Quarto content: text

1. Text, lists, images, tables, links
2. Code chunks
3. YAML metadata

Illustration by Alison Hill and Allison Horst, for RStudio.

Formatting text

• bold, italics, super^scripts & sub_scripts, strikethrough, verbatim, etc.
  
  

• Text is formatted through a markup language called Markdown (Wikipedia)

  • Other markup languages include html (webapges) and LaTeX (math)
  • All text formatting is specified via code
  • “Markdown is a plain text format that is designed to be easy to write, and, even more importantly, easy to read” ¹

• Newer versions of RStudio include a Visual editor as well that makes formatting text similar to using a word processor.

1. From Quarto’s Markdown Basics webpage, https://quarto.org/docs/authoring/markdown-basics.html

Formatting text: Visual editor

• Using the Visual editor is similar to using a wordprocessor, such as Word
• Keyboard shortcuts usually work as well (shown for Mac below)

Formatting text: Markdown

Markdown:	Output:
*This text is in italics*, but _so is this text_.	This text is in italics, but so is this text.
**Bold** also has __2 options__	Bold also has 2 options
~~Should this be deleted?~~	Should this be deleted?
Need^super^ or~sub~ scripts?	Needsuper orsub scripts?
`Code is often formatted as verbatim`	Code is often formatted as verbatim
>This is a block quote.	This is a block quote.

Headers

• Organize your documents using headers to create sections and subsections
• Use # at the beginning of the line to create headers

Text in editor:

Output:

Important

Make sure there is no space before the #, and there IS a space after the # in order for the header to work properly.

Outline of headers in RStudio

• You can easily navigate through your .qmd file if you use headers to outline your text.
• Click on the Outline button below the Run button to see the outline.

Unnumbered lists

Text in editor:

* This is an **unnumbered list**
  + with *sub-items*
      - and *sub-sub-items*,
          - or even deeper.
- You can use characters *, +, and - interchangeably to create lists.
  * The order of the 
      * character types is not important
      + and character types can be repeated.

What *is* important is the *spacing*!

+ indent each 
  * sub-level with a tab and make sure  
  * there is a __space between the character starting the list and the first bit of text__,
  *otherwise the text won't be a new bullet in the list, such as this line.
  
Also, if you do not have an empty line 
+ before starting a list, 
+ then the output will be continuous text 
- instead of bullet points.

• This is an unnumbered list
  • with sub-items
    • and sub-sub-items,
      • or even deeper.
• You can use characters *, +, and - interchangeably to create lists.
  • The order of the
    • character types is not important
    • and character types can be repeated.

What is important is the spacing!

• indent each
  • sub-level with a tab and make sure
    
  • there is a space between the character starting the list and the first bit of text, *otherwise the text won’t be a new bullet in the list, such as this line.

Also, if you do not have an empty line + before starting a list, + then the output will be continuous text - instead of bullet points.

Numbered lists

1. This is a **Numbered list**,
2. which can have
    i. sub
    ii. items
        a. and 
        b. sub-sub-items.

1. This is a Numbered list,
2. which can have
   1. sub
   2. items
      1. and
      2. sub-sub-items.

You can also 

1. create numbered lists
1. by repeating 
1. `1.` over and over again.
    i. Each bullet
    i. can start with 
    i. `1.` or `i.` 
        a. or `a.`,
        a. in theory...

When lists get interrupted

1. the numbering restarts 
1. at 1. though.

You can also

1. create numbered lists
2. by repeating
3. 1. over and over again.
   1. Each bullet
   2. can start with
   3. 1. or i.
      1. or a.,
      2. in theory…

When lists get interrupted

1. the numbering restarts
2. at 1. though.

To create a list

(@) whose numbering

does not

(@) get interrupted,
(@) use `(@)`.

To create a list

1. whose numbering

does not

2. get interrupted,
3. use (@).

To-do lists

• You can also create tasks, or to-do lists, with Quarto.
• Note that you can check off boxes in the slides!

Text in editor:

Topics to cover:

- [x] Formatting text
- [x] Headers
- [ ] Lists
    - [x] Unnumbered lists
    - [x] Numbered lists
    - [ ] To-do lists
- [ ] Hyperlinks
- [ ] Images

Topics to cover:

• Formatting text
• Headers
• Lists
  • Unnumbered lists
  • Numbered lists
  • To-do lists
• Hyperlinks
• Images

Practice

1. Part 1
   1. Using the visual editor, practice formatting text in your qmd file, such as making text bold, italicized, and in code format.
   2. Add 1^st, 2^nd, and 3^rd level headers
   3. Add a list with a
      • sub-list (bullet and/or numbered)
   4. Add a table
   5. Add whatever else you are interested in!
2. Part 2
   1. Switch back to the Source editor and examine the markdown code that was used for the formatting.

Questions: Share in the chat:

1. What went smoothly?
2. What hurdles did you encounter?

Hyperlinks

• Hyperlink where the url is visible: <url>

Workshop website link: <https://ohsu-octri-berd.github.io/Quarto_BERD_2025/>.

Workshop website link: https://ohsu-octri-berd.github.io/Quarto_BERD_2025/.

• Hyperlink showing text instead of the url: [text](url)

We also have a shortened [bitly link](https://bit.ly/berd2025_quarto).

We also have a shortened bitly link.

• Open link in a new tab: [text](url){target="_blank"}

This link will open in a new tab  
[bitly link](https://bit.ly/berd2025_quarto){target="_blank"}

This link will open in a new tab bitly link

Images (1/2)

Add an image with a simple ![](filepath)

![](/images/cat_laptop.gif)

You can add html image options to change the width or height:

Specifying width in terms of pixels:

![](/images/cat_laptop.gif){width="100"}

Specifying height in inches:

![](/images/cat_laptop.gif){height="2in"}

Specifying width as a percent of the original image size:

![](/images/cat_laptop.gif){width="50%"}

Images (2/2)

Add captions, links, and align

• Add caption text (& align left):

![Caption text](/images/ohsu_logo.jpg){width="100" fig-align="left"}

Caption text

• Add caption text that is linked to OHSU webpage (& align center):

![[Caption text with linked url](https://www.ohsu.edu){target="_blank"}]
(/images/ohsu_logo.jpg){width="100" fig-alt="OHSU Logo" fig-align="center"}

Caption text with linked url

• Logo image itself is linked to OHSU webpage (& align right):

[![](/images/ohsu_logo.jpg){width="100" fig-alt="OHSU Logo"  
fig-align="right"}](https://www.ohsu.edu){target="_blank"}

Tabsets

You can add tabbed content to webpages or slides using the standard Quarto syntax for tabsets. For example:

::: {.panel-tabset}
### Tab A

Content for `Tab A`

### Tab B

Content for `Tab B`

### Tab C

Content for `Tab C`
:::

• Each header creates a new tab.
  • The header level (# vs ## vs ###, etc.) doesn’t matter, but they all have to be the same level to create new tabsets.
  • Here we used ### level header so that the tabset appears nested within the contents of the slide, which is ## level.
• See the next slide for the rendered output of the tabset code above.

Tabsets - Rendered

Below is the rendered output of the tabset code on the previous slide:

• Tab A
• Tab B
• Tab C

Content for Tab A

Content for Tab B

Content for Tab C

Callout Blocks ⚠️ (1/2)

::: callout-tip
Callouts are an excellent way to 
draw attention to specific 
pieces of information.
:::

::: {.callout-note}
They are especially useful for 
notes, warnings, or tips.
:::

::: {.callout-important}
You create them using fenced 
divs `:::` with a special class.
:::

Tip

Callouts are an excellent way to draw attention to specific pieces of information.

Note

They are especially useful for notes, warnings, or tips.

Important

You create them using fenced divs ::: with a special class.

::: callout-caution
There are 5 types of callouts.
:::

::: callout-warning
It is tempting to overdo it 
with callout boxes!
:::

Caution

There are 5 types of callouts.

Warning

It is tempting to overdo it with callout boxes!

Callout Blocks ⚠️ (2/2)

::: {.callout-tip}
## Tip with different title

You can change the title of any 
type of callout box by adding 
`## New title` right below the 
first line of the callout. 
:::

::: {.callout-note icon=false}
You can omit the icon of any type 
of callout box by adding 
`icon=false` within the `{}` of 
the first line of the callout. 
:::

Tip with different title

You can change the title of any type of callout box by adding ## New title right below the first line of the callout.

Note

You can omit the icon of any type of callout box by adding icon=false within the {} of the first line of the callout.

::: {.callout-caution collapse="true"}
## Callouts can be collapsed in 
html files (not in slides - yet)

If you look at the html file 
(not the slides), you will see 
that the content of this callout 
is "folded" and needs to be expanded 
by the user to see it. 
* Use `collapse="true"` if you want it 
collapsed by default, and 
* `collapse="false"` to make it 
expanded by default.
:::

Callouts can be collapsed in html files (not in slides - yet)

• If you look at the html file (not the slides), you will see that the content of this callout is “folded” and needs to be expanded by the user to see it.
• Use collapse="true" if you want it collapsed by default, and
• collapse="false" to make it expanded by default.

Learn more about callout blocks at https://quarto.org/docs/authoring/callouts.html

Tables

One benefit of using or switching over to the Visual editor is that it is much easier to add tables.

| Name    | Date     | Measure |
|---------|----------|---------|
| Jessica | 02/04/25 | 9.3     |
| Meike   | 01/03/25 | 10.1    |
| BERD    |    🐦    | 10.5    |

Name	Date	Measure
Jessica	02/04/25	9.3
Meike	01/03/25	10.1
BERD	🐦	10.5

Important

• When creating tables summarizing data or showing regression output, this is NOT the way to create them.
  
• Use code chunks and table options within R to create them instead.

Equations with LaTeX

• Mathematical equations and symbols can be included using LaTeX, both as inline equations or centered display equations

* Use single `$` for inline equations: $y=\beta_0 + \beta_1x + \varepsilon$

• Use single $ for inline equations: \(y=\beta_0 + \beta_1x + \varepsilon\)

* Use double `$$` for centered display equations:
  
$$\hat{y}= \frac{3}{7} +  5 \textrm{age} + 3^2 \cdot \textrm{height}$$ 

• Use double $$ for centered display equations:

\[\hat{y}= \frac{3}{7} + 5 \textrm{age} + 3^2 \cdot \textrm{height}\]

3 types of Quarto content: code

• 1. Text, lists, images, tables, links
• 2. Code chunks
• 3. YAML metadata

Illustration by Alison Hill and Allison Horst, for RStudio.

Code chunks

.qmd file

html output

What does a code chunk look like?

An empty code chunk looks like this:

Visual editor

Source editor

Important

Note that a code chunks start with ```{r} and ends with ```. Make sure there is no space before ```.

Enter and run code (1/2)

• Type R code inside code chunks
• Select code you want to run, by
  • placing the cursor in the line of code you want to run,
  • or highlighting the code you want to run

• Run selected code by
  • clicking on the button in the top right corner of the scripting window and choosing Run Selected Line(s),
  • or typing one of the following key combinations:

Mac	ctrl + return
PC	command + return

• Where does the output appear?

Enter and run code (2/2)

• Run all code in a chunk by
  • by clicking the play button in the top right corner of the chunk
• The code output appears below the code chunk

Note

• The output should also appear in the Console.
• Settings can be changed so that the output appears only in the Console and not below the code chunk:
  • Select (to right of Render button) and then Chunk Output in Console.

Create a code chunk

3 options to create a code chunk

1. Click on at top right of the editor window, or

2. Keyboard shortcut

Mac	Command + Option + I
PC	Ctrl + Alt + I

3. Visual editor: Select Insert -> Executable Cell -> R

Useful keyboard shortcuts

Full list of keyboard shortcuts

action	mac	windows/linux
Run code in qmd (or script)	cmd + enter	ctrl + enter
<-	option + -	alt + -
interrupt currently running command	esc	esc
keyboard shortcut help	option + shift + k	alt + shift + k

Practice: Try typing code below in your qmd (with shortcut) and evaluating it (with shortcut):

y <- 5
y

Code chunk options

• eval
• echo
• Other options
• Set options globally

• eval determines whether the R code is run or not.
• The default is true.
• When set to false, the code is not run but still displayed in the output:

#| eval: true

```{r}
#| eval: true

y <- 1:10
mean(y)
```

[1] 5.5

#| eval: false

```{r}
#| eval: false

y <- 1:10
mean(y)
```

• echo determines whether the R code is displayed or not.
• The default is true. When set to false, the code is not displayed in the output but the output is (if eval is set to true):

#| echo: true

Code chunk:

Output:

y <- 1:10
mean(y)

[1] 5.5

#| echo: false

Code chunk:

Output:

[1] 5.5

• warning: do you want R’s warnings include in your output?
• message: do you want R’s messages include in your output?

For a complete list of options, see the Quarto reference page for Code Cells: Knitr. In particular the sections on Code Output and Cell Output.

• Usually you want most of your document to have the same code chunk options.
• You can set these options in the YAML of the Quarto file (next topic!).

3 types of Quarto content: YAML

• 1. Text, lists, images, tables, links
• 2. Code chunks
• 3. YAML metadata

Illustration by Alison Hill and Allison Horst, for RStudio.

YAML metadata

Many output options can be set in the YAML metadata, which is the first set of code in the file starting and ending with ---.

• It sets the configuration specifications for the output file
• YAML is an acronym for
  • yet another markup language, or
  • YAML ain’t markup language

Simple YAML example

• The default YAML includes a title and author that appear at the top of the output file. In the example below, I also added in a date option

YAML:

---
title: "My first Quarto file"
author: "Meike"
date: "9/25/2023"
format: html
editor: visual
---

Output:

Important

• The YAML must start and end with 3 dashes ---.
• The first set of --- must be on the very first line.

Change the output file type

• The YAML specifies the format of the output file:
  • html, Word, pdf, slides, website, book, etc.
• This is done by changing the format: option

Illustration by Alison Hill and Allison Horst, for RStudio.

---
title: "My first Quarto file"
author: "Meike"
date: "9/25/2023"
format: html
editor: visual
---

Output format	YAML
html	format: html
Word	format: docx
pdf1	format: pdf
html slides	format: revealjs
PPT slides	format: pptx

1. requires LaTeX installation

Practice

• Change the format of the qmd file to revealjs and render the file.
  • How do the slides look?
  • What in the code determines when a new slide is created?
• Change the format of the qmd file to pptx and render the file.
  • How do the slides look? Which styling options worked and which did not?
  • What in the code determines when a new slide is created?
• Change the format of the qmd file to docx and render the file.
  • How does the Word doc look? Which styling options worked and which did not?

YAML customizations

• Below are some YAML options to customize your html file.
  
• Download from GitHub the file part2_intro_code_yaml_extra.qmd to render it on your computer.
  • You can view the rendered version online. This will look different from on your computer though since the workshop’s website’s setting are being applied to it.
• Learn about many more YAML options from Quarto’s HTML Options page.

---
title: "Part 2: Quarto Introduction"
pagetitle: "Part 2: Quarto Introduction"
subtitle: "OCTRI-BERD Workshop July 2025"
author: "Jessica Minnier, Meike Niederhausen"
institute: "OHSU-PSU School of Public Health"
date: "7/17/25"
format:
  html:
    link-external-newwindow: true  # open links in a new tab
    toc: true                      # create a table of contents
    number-sections: true         # numbers header sections
    embed-resources: true          # IMPORTANT! Creates a standalone html file that other can view without needing additional files.
    code-fold: show                # true collapses all code chunks; show shows the code
    code-tools: true               # creates menu at top of html to toggle code folding
execute:
  echo: true                      # show all code in code chunks
  eval: true                      # run all code in code chunks 
editor: source                    # other options is visual
# editor_options: 
#   chunk_output_type: console      # Code output shown in console instead of inline
---