Quarto and R Markdown Tutorial
R Markdown Overview
R Markdown combines markdown (an easy to write plain text format) with embedded R code chunks. When compiling R Markdown documents, the code components can be evaluated so that both the code and its output can be included in the final document. This makes analysis reports highly reproducible by allowing to automatically regenerate them when the underlying R code or data changes. R Markdown documents (.Rmd files) can be rendered to various formats including HTML and PDF. The R code in an .Rmd document is processed by knitr, while the resulting .md file is rendered by pandoc to the final output formats (e.g. HTML or PDF). Historically, R Markdown is an extension of the older Sweave/Latex environment. Rendering of mathematical expressions and reference management is also supported by R Markdown using embedded Latex syntax and Bibtex, respectively. A successor publishing environment is Quarto (.qmd files), which is covered in the Quarto section below. Note that this tutorial itself is written as a .qmd file, meaning all examples shown in the R Markdown sections render identically in Quarto.
Quick Start
Install R Markdown
To work with this tutorial, the rmarkdown package needs to be installed on a system.
Initialize a new R Markdown (Rmd) script
To minimize typing, it can be helful to start with an R Markdown template and then modify it as needed. Note the file name of an R Markdown scirpt needs to have the extension .Rmd. Template files for the following examples are available here:
- R Markdown sample script:
sample.Rmd - Bibtex file for handling citations and reference section:
bibtex.bib
Users want to download these files, open the sample.Rmd file with their preferred R IDE (e.g. RStudio, vim or emacs), initilize an R session and then direct their R session to the location of these two files.
Metadata section
The metadata section (YAML header) in an R Markdown script defines how it will be processed and rendered. The metadata section also includes both title, author, and date information as well as options for customizing the output format. For instance, PDF and HTML output can be defined with pdf_document and html_document, respectively. The BiocStyle:: prefix will use the formatting style of the BiocStyle package from Bioconductor.
---
title: "My First R Markdown Document"
author: "Author: First Last"
date: "Last update: 19 May, 2026"
output:
BiocStyle::html_document:
toc: true
toc_depth: 3
fig_caption: yes
fontsize: 14pt
bibliography: bibtex.bib
---Render Rmd script
An R Markdown script can be evaluated and rendered with the following render command or by pressing the knit button in RStudio. The output_format argument defines the format of the output (e.g. html_document or pdf_document). The setting output_format="all" will generate all supported output formats. Alternatively, one can specify several output formats in the metadata section.
The following shows two options how to run the rendering from the command-line. To render to PDF format, use the argument setting: output_format="pdf_document".
Alternatively, one can use a Makefile to evaluate and render an R Markdown script. A sample Makefile for rendering the above sample.Rmd can be downloaded here. To apply it to a custom Rmd file, one needs open the Makefile in a text editor and change the value assigned to MAIN (line 13) to the base name of the corresponding .Rmd file (e.g. assign systemPipeRNAseq if the file name is systemPipeRNAseq.Rmd). To execute the Makefile, run the following command from the command-line.
R code chunks
R Code Chunks can be embedded in an R Markdown script by using three backticks at the beginning of a new line along with arguments enclosed in curly braces controlling the behavior of the code. The following lines contain the plain R code. A code chunk is terminated by a new line starting with three backticks. The following shows an example of such a code chunk. Note the backslashes are not part of it. They have been added to print the code chunk syntax in this document.
```\{r code_chunk_name, eval=FALSE\}
x <- 1:10
```
The following lists the most important arguments to control the behavior of R code chunks:
r: specifies language for code chunk, here Rchode_chunk_name: name of code chunk; this name needs to be unique within an Rmdeval: if assignedTRUEthe code will be evaluatedwarning: if assignedFALSEwarnings will not be shownmessage: if assignedFALSEmessages will not be showncache: if assignedTRUEresults will be cached to reuse in future rendering instancesfig.height: allows to specify height of figures in inchesfig.width: allows to specify width of figures in inches
For more details on code chunk options see here. If document rendering of code chunk sections becomes time consuming due to long computations, one can enable caching to improve performance. The corresponding cache options of the knitr package describes how caching works and the cache examples here provide additional details.
Learning Markdown
The basic syntax of Markdown and derivatives like kramdown is extremely easy to learn. Rather than providing another introduction on this topic, here are some useful sites for learning Markdown:
Tables
There are several ways to render tables. First, they can be printed within the R code chunks. Second, much nicer formatted tables can be generated with the functions kable, kableExtra, pander or xtable. The following example uses kable from the knitr package.
With knitr::kable
| Sepal.Length | Sepal.Width | Petal.Length | Petal.Width | Species |
|---|---|---|---|---|
| 5.1 | 3.5 | 1.4 | 0.2 | setosa |
| 4.9 | 3.0 | 1.4 | 0.2 | setosa |
| 4.7 | 3.2 | 1.3 | 0.2 | setosa |
| 4.6 | 3.1 | 1.5 | 0.2 | setosa |
| 5.0 | 3.6 | 1.4 | 0.2 | setosa |
| 5.4 | 3.9 | 1.7 | 0.4 | setosa |
| 4.6 | 3.4 | 1.4 | 0.3 | setosa |
| 5.0 | 3.4 | 1.5 | 0.2 | setosa |
| 4.4 | 2.9 | 1.4 | 0.2 | setosa |
| 4.9 | 3.1 | 1.5 | 0.1 | setosa |
| 5.4 | 3.7 | 1.5 | 0.2 | setosa |
| 4.8 | 3.4 | 1.6 | 0.2 | setosa |
A much more elegant and powerful solution is to create fully interactive tables with the DT package. This JavaScirpt based environment provides a wrapper to the DataTables library using jQuery. The resulting tables can be sorted, queried and resized by the user. Note, R Markdown source files containing JavaScript components can only be rendered into HTML and not PDF.
With DT::datatable
Figures
Plots generated by the R code chunks in an R Markdown document can be automatically inserted in the output file. The size of the figure can be controlled with the fig.height and fig.width arguments.
library(ggplot2)
dsmall <- diamonds[sample(nrow(diamonds), 1000), ]
ggplot(dsmall, aes(color, price/carat)) + geom_jitter(alpha = I(1 / 2), aes(color=color))
Sometimes it can be useful to explicitly write an image to a file and then insert that image into the final document by referencing its file name in the R Markdown source. For instance, this can be useful for time consuming analyses. The following code will generate a file named myplot.png. To insert the file in the final document, one can use standard Markdown or HTML syntax, e.g.: <img src="myplot.png"/>.
png("myplot.png")
ggplot(dsmall, aes(color, price/carat)) + geom_jitter(alpha = I(1 / 2), aes(color=color))
dev.off()png
2 
Custom functions
Custom functions can be kept in a separate R file (here custom_Fct.R) and then imported with the source() command. In the following example, the custom_Fct.R file is located on GitHub.
Now the imported function (here myMAcomp) can be used.
myMA <- matrix(rnorm(100000), 10000, 10, dimnames=list(1:10000, paste("C", 1:10, sep="")))
resultDF <- myMAcomp(myMA=myMA, group=c(1,1,1,2,2,2,3,3,4,4), myfct=mean)
kable(resultDF[1:12,])| C1_C2_C3 | C4_C5_C6 | C7_C8 | C9_C10 |
|---|---|---|---|
| -0.3757884 | -1.8443214 | 0.5259585 | -1.4467488 |
| -0.5205442 | -0.2651853 | 0.0137996 | 0.1850311 |
| -1.6166195 | 0.7560664 | 0.4952670 | -0.3422933 |
| -0.4127279 | 0.1066787 | -0.8859878 | 1.2112472 |
| 0.0770526 | 0.8084343 | 0.0456972 | -0.3735521 |
| 0.2272966 | -0.4481135 | -0.1959607 | -1.0051298 |
| 0.2834368 | 0.5014831 | -0.1420058 | -0.1714637 |
| 0.5043950 | 0.1646151 | -0.6713876 | -0.8640138 |
| -0.2568442 | 0.4373165 | -0.1953747 | -0.3151377 |
| 0.4075784 | -0.0819149 | 0.5759540 | 0.3470885 |
| 0.0404368 | 0.5337678 | -0.2266180 | -0.0314990 |
| 0.2573220 | -0.7921693 | -0.0990370 | 0.5140947 |
Inline R code
To evaluate R code inline, one can enclose an R expression with a single back-tick followed by r and then the actual expression. For instance, the back-ticked version of ‘r 1 + 1’ evaluates to 2 and ‘r pi’ evaluates to 3.1415927.
Mathematical equations
To render mathematical equations, one can use standard Latex syntax. When expressions are enclosed with single $ signs then they will be shown inline, while enclosing them with double $$ signs will show them in display mode. For instance, the following Latex syntax d(X,Y) = \sqrt[]{ \sum_{i=1}^{n}{(x_{i}-y_{i})^2} } renders in display mode as follows:
\[d(X,Y) = \sqrt[]{ \sum_{i=1}^{n}{(x_{i}-y_{i})^2} }\]
To learn LaTeX syntax for mathematical equations, one can consult various online manuals, such as this Wikibooks tutorial, or use an online equation rendering and checking tool, such as this one.
Citations and bibliographies
Citations and bibliographies can be autogenerated in R Markdown in a similar way as in Latex/Bibtex. Reference collections should be stored in a separate file in Bibtex or other supported formats. To cite a publication in an R Markdown script, one uses the syntax [@<id1>] where <id1> needs to be replaced with a reference identifier present in the Bibtex database listed in the metadata section of the R Markdown script (e.g. bibtex.bib). For instance, to cite Lawrence et al. (2013), one uses its reference identifier (e.g. Lawrence2013-kt) as <id1> (Lawrence et al. 2013). This will place the citation inline in the text and add the corresponding reference to a reference list at the end of the output document. For the latter a special section called References needs to be specified at the end of the R Markdown script. To fine control the formatting of citations and reference lists, users want to consult this R Markdown page. Also, for general reference management and obtaining references in Bibtex format Paperpile can be very helpful.
Viewing R Markdown report on HPCC cluster
R Markdown reports located on UCR’s HPCC Cluster can be viewed locally in a web browser (without moving the source HTML) by creating a symbolic link from a user’s .html directory. This way any updates to the report will show up immediately without creating another copy of the HTML file. For instance, if user ttest has generated an R Markdown report under ~/bigdata/today/rmarkdown/sample.html, then the symbolic link can be created as follows:
After this one can view the report in a web browser using this URL https://cluster.hpcc.ucr.edu/~ttest/rmarkdown/sample.html. If necessary access to the URL can be restricted with a password following the instructions here. Very important: to set up accounts for html viewing, users have to apply the configuration settings for their accounts that are outlined on the HPCC website here.
Viewing R Markdown report on GitHub
To host and view static HTML files on GitHub, follow the instructions here. Note, this works only with public GitHub repos.
Quarto Overview
Quarto is the next-generation publishing system from Posit (formerly RStudio) that supersedes R Markdown. It uses the same underlying tools — knitr for executing R code and pandoc for converting the resulting Markdown to output formats — so the design model and most of the syntax carry over directly. The key differences are that Quarto is language-agnostic (R, Python, Julia and Observable JS are all first-class citizens in the same document), uses a unified format: key in the YAML header instead of output:, and moves chunk options from the {r ...} header line to special #| comment lines inside the chunk. Because course projects in GEN242 must be submitted as .qmd files rendered through Quarto, this section covers everything needed to write and render them. The Rmd vs Quarto comparison table at the end of this section summarises the differences at a glance.
Install Quarto
Quarto is a standalone command-line tool that ships bundled with recent versions of RStudio (≥ 2022.07). For standalone installation or to update to the latest release, download the installer for your platform from https://quarto.org/docs/get-started/. The companion R package quarto provides convenience wrappers for rendering from within an R session.
To confirm that the Quarto CLI is available, run the following in a terminal.
Initialize a new Quarto (.qmd) script
Quarto source files use the .qmd extension. The simplest way to start is to copy an existing .qmd file (such as this tutorial) and adapt it. A minimal template and the shared Bibtex file are available here:
- Quarto sample script:
sample.qmd - Bibtex file (shared with R Markdown):
bibtex.bib
Metadata section
The YAML header of a .qmd file uses format: instead of output: to specify the output format and its options. The structure is otherwise very similar to R Markdown. The following example produces a standalone HTML document with a floating table of contents and numbered sections, which is the recommended format for GEN242 course project reports.
---
title: "My First Quarto Document"
author: "Author: First Last"
date: last-modified
format:
html:
toc: true
toc-depth: 3
number-sections: true
fig-cap-location: bottom
bibliography: bibtex.bib
---Key differences from the R Markdown YAML header:
format:replacesoutput:; the sub-key is the format name (e.g.html,pdf,docx)- Option names use kebab-case (
toc-depth,number-sections) instead of underscores date: last-modifiedautomatically inserts the file modification date without any inline R expressionBiocStyleis not used; Quarto has its own theming system viatheme:underformat: html:
To produce PDF output, change html: to pdf:. To generate both formats in one render pass, list them both under format:.
format:
html:
toc: true
pdf:
toc: trueRender .qmd script
A Quarto document can be rendered from R or from the command-line. In RStudio, the Render button (replacing the old Knit button) triggers rendering.
From the command-line:
Code chunks
Quarto code chunks open identically to R Markdown — three backticks followed by the language name in curly braces. The difference is that chunk options are written as #| comment lines inside the chunk rather than as comma-separated arguments on the opening line. Both styles are accepted by Quarto for backward compatibility, but the #| style is preferred because it works consistently across all execution engines (knitr and Jupyter) and is easier to read and edit for long option lists.
R Markdown style (still accepted by Quarto):
```\{r chunk_name, eval=FALSE, fig.height=4\}
x <- 1:10
```Quarto style (preferred):
```\{r chunk_name\}
#| eval: false
#| fig-height: 4
x <- 1:10
```The most important chunk options and their Quarto equivalents are listed below. Note that option names switch from dot-separated to kebab-case in Quarto.
| R Markdown option | Quarto #\| option |
Effect |
|---|---|---|
eval=TRUE/FALSE |
#\| eval: true/false |
Execute the chunk |
echo=TRUE/FALSE |
#\| echo: true/false |
Show source code |
warning=FALSE |
#\| warning: false |
Suppress warnings |
message=FALSE |
#\| message: false |
Suppress messages |
cache=TRUE |
#\| cache: true |
Cache results |
fig.height=4 |
#\| fig-height: 4 |
Figure height (inches) |
fig.width=6 |
#\| fig-width: 6 |
Figure width (inches) |
fig.cap="..." |
#\| fig-cap: "..." |
Figure caption |
out.width="80%" |
#\| out-width: "80%" |
Rendered figure width |
Document-wide defaults for chunk options can be set once in the YAML header under execute:, avoiding repetition across chunks.
---
execute:
echo: true
warning: false
message: false
---
Inline R code
Inline R code works identically to R Markdown. An inline expression is written as a backtick followed by the letter r, a space, the R expression, and a closing backtick. For instance, writing nrow(iris) as an inline R expression evaluates to 150 (the number of rows in iris). Quarto additionally supports inline expressions for Python and Julia by replacing r with python or julia respectively, when those engines are active.
Figures and cross-references
Figure insertion and sizing work the same way as in R Markdown. Quarto additionally supports a native cross-referencing system that does not require any extra packages. A figure produced by a code chunk can be cross-referenced by giving the chunk a label that starts with fig-:
```\{r\}
#| label: fig-jitter
#| fig-cap: "Diamond price by color."
#| fig-height: 4
ggplot(dsmall, aes(color, price/carat)) +
geom_jitter(alpha = 0.5, aes(color = color))
```Elsewhere in the document, @fig-jitter renders as a numbered hyperlink (e.g. “Figure 1”). The same scheme applies to tables (tbl- prefix) and sections (sec- prefix, requires number-sections: true in the YAML header).
Callout blocks
Quarto introduces callout blocks, a convenient way to highlight notes, warnings, tips and important information in a visually distinct box. They are written with a fenced ::: div syntax and are not available in standard R Markdown.
::: {.callout-note}
This is a note callout. Use `.callout-tip`, `.callout-warning`, `.callout-important`,
or `.callout-caution` for other styles.
:::This is a note callout. Use .callout-tip, .callout-warning, .callout-important, or .callout-caution for other styles.
Callout blocks can also have titles: add ## My Title as the first line inside the block.
JavaScript-dependent output (e.g. DT::datatable) can only be rendered to HTML, not PDF — this applies to both R Markdown and Quarto.
Quarto projects and _quarto.yml
When a .qmd file is part of a larger website or book (such as the GEN242 course site), project-level settings are controlled by a _quarto.yml file in the root directory of the project. Individual .qmd files inherit these settings and only need to specify document-specific overrides in their own YAML headers. The GEN242 site _quarto.yml sets the sidebar, navigation, default theme, and bibliography, which is why the YAML headers of tutorial pages like this one are short. Students writing course project reports as standalone files do not need a _quarto.yml and should include all needed settings in the document YAML header directly.
Viewing a Quarto report on the HPCC cluster
Quarto HTML output can be viewed on the HPCC cluster using the same symbolic-link approach described for R Markdown above. After rendering sample.qmd to sample.html, create the link as follows:
The report is then accessible at https://cluster.hpcc.ucr.edu/~<username>/quarto/sample.html.
Viewing a Quarto report on GitHub
Quarto HTML files can be hosted on GitHub Pages using the same workflow as R Markdown HTML files. Follow the instructions here. Quarto also has dedicated support for publishing to GitHub Pages via quarto publish gh-pages; see the Quarto publishing documentation for details.
Rmd vs Quarto comparison
The table below summarises the most important syntax differences between R Markdown and Quarto for the features covered in this tutorial. Everything not listed here is identical between the two systems.
| Feature | R Markdown (.Rmd) |
Quarto (.qmd) |
|---|---|---|
| Output format key | output: html_document |
format: html |
| HTML with TOC | output: html_document: toc: true |
format: html: toc: true |
| Option naming style | toc_depth, fig_caption |
toc-depth, fig-cap-location |
| Date | format(Sys.time(), ...) as inline R |
last-modified |
| Chunk options | {r name, eval=FALSE, fig.height=4} |
#\| eval: false / #\| fig-height: 4 |
| Global chunk defaults | knitr::opts_chunk$set(...) |
execute: block in YAML |
| Render from R | rmarkdown::render("file.Rmd") |
quarto::quarto_render("file.qmd") |
| Render from CLI | Rscript -e "rmarkdown::render(...)" |
quarto render file.qmd |
| Figure cross-refs | requires bookdown output format |
native via @fig-label |
| Callout blocks | not available | ::: {.callout-note} |
| Multi-language chunks | R only (or via reticulate) |
R, Python, Julia, Observable natively |
| Project config | _site.yml / _bookdown.yml |
_quarto.yml |
| Math, citations, Bibtex | [@key], $...$, $$...$$ |
identical |
knitr::kable, DT, ggplot |
standard | identical |
| Inline R code | backtick + r + expression + backtick |
identical |
Additional Quarto documentation and learning resources:
Session Info
R version 4.5.3 (2026-03-11)
Platform: x86_64-pc-linux-gnu
Running under: Debian GNU/Linux 12 (bookworm)
Matrix products: default
BLAS: /usr/lib/x86_64-linux-gnu/blas/libblas.so.3.11.0
LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.11.0 LAPACK version 3.11.0
locale:
[1] LC_CTYPE=en_US.UTF-8 LC_NUMERIC=C LC_TIME=en_US.UTF-8 LC_COLLATE=en_US.UTF-8 LC_MONETARY=en_US.UTF-8 LC_MESSAGES=en_US.UTF-8 LC_PAPER=en_US.UTF-8 LC_NAME=C
[9] LC_ADDRESS=C LC_TELEPHONE=C LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C
time zone: America/Los_Angeles
tzcode source: system (glibc)
attached base packages:
[1] stats graphics grDevices utils datasets methods base
other attached packages:
[1] ggplot2_4.0.2 DT_0.34.0 knitr_1.51
loaded via a namespace (and not attached):
[1] vctrs_0.7.1 cli_3.6.5 rlang_1.1.7 xfun_0.56 otel_0.2.0 generics_0.1.4 S7_0.2.1 jsonlite_2.0.0 glue_1.8.0 htmltools_0.5.9 scales_1.4.0
[12] rmarkdown_2.30 grid_4.5.3 tibble_3.3.1 evaluate_1.0.5 fastmap_1.2.0 yaml_2.3.12 lifecycle_1.0.5 compiler_4.5.3 codetools_0.2-20 dplyr_1.2.0 RColorBrewer_1.1-3
[23] pkgconfig_2.0.3 htmlwidgets_1.6.4 farver_2.1.2 digest_0.6.39 R6_2.6.1 tidyselect_1.2.1 dichromat_2.0-0.1 pillar_1.11.1 magrittr_2.0.4 withr_3.0.2 tools_4.5.3
[34] gtable_0.3.6