Quarto & R Markdown

Outline

• Overview
• Structure of Quarto Documents
• Inline R, Math & Citations
• R Markdown
• Sharing Reports
• Summary

What are Quarto and R Markdown?

Literate programming for science

Environments that combine narrative text with executable code. When rendered, code is executed and its output — tables, figures, equations — is woven into a polished HTML, PDF, or Word document.

Why use them?

Quarto vs R Markdown

• Quarto (.qmd) — current recommended system; used for all GEN242 course projects
• R Markdown (.Rmd) — predecessor; still abundant in Bioconductor vignettes and published R workflows
• Both use the same toolchain: knitr executes R → pandoc converts to HTML/PDF
• Nearly everything learned for one transfers directly to the other

Markdown Formatting - Quick Reference

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

Outline

• Overview
• Structure of Quarto Documents
• Inline R, Math & Citations
• R Markdown
• Sharing Reports
• Summary

Getting Started

Installation

Quarto ships with RStudio ≥ 2022.07. Standalone install or updates: https://quarto.org/docs/get-started/

install.packages("quarto")   # optional R wrapper

quarto check                 # verify CLI is available

Template files for GEN242

• sample.qmd — Quarto template
• bibtex.bib — reference file

Or in RStudio: File → New File → Quarto Document

Rendering

From R:

quarto::quarto_render("sample.qmd")                      # HTML (from YAML)
quarto::quarto_render("sample.qmd", output_format="pdf") # override to PDF

From the command line:

quarto render sample.qmd
quarto render sample.qmd --to pdf

In RStudio: click the Render button or press Ctrl+Shift+K

YAML Header

Recommended header for GEN242 project reports

---
title: "My Project Report"
author: "Author: First Last"
date: last-modified
format:
  html:
    theme: flatly        # alternatives: cosmo, lumen, default
    toc: true
    toc-depth: 3
    number-sections: true
    fig-cap-location: bottom
    embed-resources: true   # single self-contained HTML file
bibliography: bibtex.bib
---

Key YAML options

Full options reference: https://quarto.org/docs/reference/formats/html.html

Document-wide chunk defaults

Set once in the YAML — applies to every chunk unless overridden individually:

execute:
  echo: true
  warning: false
  message: false

Code Chunks

Quarto chunk syntax

```{r chunk_name}
#| eval: true
#| echo: true
#| warning: false
#| fig-height: 4
#| fig-cap: "Diamond price by color"

ggplot(dsmall, aes(color, price/carat)) +
  geom_jitter(alpha = 0.5, aes(color = color))
```

Options are written as #| comment lines inside the chunk — one per line.

Most important chunk options

Full reference: https://quarto.org/docs/reference/cells/cells-knitr.html

Cross-referencing figures

```{r}
#| label: fig-diamonds
#| fig-cap: "Diamond price by color."
ggplot(dsmall, aes(color, price/carat)) +
  geom_jitter(alpha = 0.5, aes(color = color))
```

In prose: As shown in @fig-diamonds, price varies by color.
Renders as: “As shown in Figure 1, price varies by color.”

The same scheme works for tables (tbl- prefix) and sections (sec- prefix).

Tables

Static tables with knitr::kable

library(knitr)
kable(iris[1:6, ])

Clean, publication-ready. Works for both HTML and PDF output.

Interactive tables with DT::datatable

library(DT)
datatable(iris)

Sortable, filterable, paginated — HTML output only.

Figures

Auto-generated figures

library(ggplot2)
dsmall <- diamonds[sample(nrow(diamonds), 1000), ]
ggplot(dsmall, aes(color, price/carat)) +
  geom_jitter(alpha = 0.5, aes(color = color))

Figure size is controlled with fig-height and fig-width chunk options, or globally under execute: in the YAML header.

Pre-generated figures

Write to file and insert by path — useful when figure generation is slow:

png("myplot.png")
ggplot(...) + geom_jitter(...)
dev.off()

![Caption text](myplot.png){fig-align="center"}

Outline

• Overview
• Structure of Quarto Documents
• Inline R, Math & Citations
• R Markdown
• Sharing Reports
• Summary

Inline R, Math & Citations

Inline R code

Embed evaluated R expressions directly in prose by enclosing them with a backtick, the letter r, a space, the expression, and a closing backtick.

Example: writing the expression nrow(iris) inline evaluates to 150 at render time.

Quarto also supports inline Python and Julia expressions when those engines are active.

Mathematical equations

Standard LaTeX syntax — $...$ for inline, $$...$$ for display:

$$d(X,Y) = \sqrt{ \sum_{i=1}^{n}{(x_i - y_i)^2} }$$

Renders as:

\[d(X,Y) = \sqrt{ \sum_{i=1}^{n}{(x_i - y_i)^2} }\]

LaTeX math reference: https://en.wikibooks.org/wiki/LaTeX/Mathematics

Citations and bibliographies

Store references in a .bib file, list it under bibliography: in the YAML header, then cite with [@key]:

Genomic ranges were processed using GenomicRanges [@Lawrence2013-kt].

• Renders inline and auto-generates the reference list at the end of the document
• Use Paperpile to manage references and export BibTeX
• Fine-grained formatting: Quarto citations docs

Additional Quarto Features

_quarto.yml — project-level configuration

When multiple .qmd files form a website or course site, a _quarto.yml file in the project root controls shared settings. Individual files inherit and only override what they need.

project:
  type: website
  output-dir: docs

website:
  title: "My Site"
  navbar:
    left:
      - href: index.qmd
        text: Home

format:
  html:
    theme: cosmo
    toc: true

Other output formats from the same source

Jupyter notebooks and Python

.ipynb files can be rendered directly:

quarto render notebook.ipynb

Or use the Jupyter engine in a .qmd:

---
jupyter: python3
---

See the Quarto Python documentation.

Outline

• Overview
• Structure of Quarto Documents
• Inline R, Math & Citations
• R Markdown
• Sharing Reports
• Summary

R Markdown

What is R Markdown?

The predecessor to Quarto — same knitr/pandoc toolchain, very similar syntax. Still widely used: most Bioconductor package vignettes are written in R Markdown.

YAML header

---
title: "My R Markdown Document"
author: "Author: First Last"
date: "Last update: 27 May, 2026"
output:
  BiocStyle::html_document:
    toc: true
    toc_depth: 3
    fig_caption: yes
fontsize: 14pt
bibliography: bibtex.bib
---

Key difference from Quarto: output: instead of format:, underscore option names (toc_depth) instead of kebab-case (toc-depth).

Code chunk syntax

```{r chunk_name, eval=FALSE, fig.height=4}
x <- 1:10
```

Options are comma-separated on the opening line rather than #| lines inside.

Rendering

rmarkdown::render("sample.Rmd", output_format="BiocStyle::html_document")

Rscript -e "rmarkdown::render('sample.Rmd', clean=TRUE)"

Template: sample.Rmd

Outline

• Overview
• Structure of Quarto Documents
• Inline R, Math & Citations
• R Markdown
• Sharing Reports
• Summary

Sharing Reports

Self-contained output for submission

Add embed-resources: true to bundle all CSS, JS, and figures into a single HTML file:

format:
  html:
    embed-resources: true

Ideal for submitting course reports — no broken links, no missing images.

Viewing on the HPCC cluster

Render locally, then create a symbolic link from your .html directory:

cd ~/.html
ln -s ~/bigdata/today/rmarkdown/sample.html sample.html

View at: https://cluster.hpcc.ucr.edu/~ttest/rmarkdown/sample.html

Follow the HPCC setup instructions to enable HTML viewing for your account.

Hosting on GitHub Pages

For public GitHub repositories, follow the instructions here.

Quarto also has native GitHub Pages support:

quarto publish gh-pages

See the Quarto publishing documentation.

Outline

• Overview
• Structure of Quarto Documents
• Inline R, Math & Citations
• R Markdown
• Sharing Reports
• Summary

Quarto vs R Markdown

What is identical

Markdown prose · LaTeX math · Bibtex citations · knitr::kable · DT::datatable · ggplot2 · inline R code · knitr/pandoc render pipeline

Key syntax differences

Practical advice

• Use Quarto for all new work, including GEN242 course projects
• Read R Markdown when consulting Bioconductor vignettes — syntax is very close
• Quarto renders most .Rmd-style chunk headers correctly (backward compatible)