Quarto Tips & Tricks

quarto

html

pdf

formatting

data science

Author

Dr. Adrian Correndo

Published

January 9, 2026

1 Introduction

Quarto is a powerful tool for creating dynamic documents, and it supports multiple output formats, including HTML and PDF. This article presents essential tips and tricks to help you customize and optimize your Quarto documents effectively.

2 What is Quarto?

We are going to explore the new features offered by Quarto documents (*.qmd).

Quarto is a refined version (and successor) of R-markdown. It is an open-source scientific and technical publishing system built on Pandoc. It allows to combine R, Python, Julia, and Java (Observable JS) for the design of reports, applications, websites, blogs, scientific publications, and more…

3 General Formatting Tips

YAML Configuration:
- Use title, author, date, and categories to structure metadata.
- Enable table of contents (toc: true) and section numbering (number-sections: true).
- For citations, link your bibliography file and enable link-citations: true.
Organizing Content:
- Use # for sections and ## for subsections.
- Inline code: Use `code` for inline formatting.
- Block code: Use triple backticks ```r for code chunks.
- Use ::: {.callout-note} for special notes in Quarto.
- Add cross-references using (@fig:name) for figures and (@tbl:name) for tables.

4 Citing References in Quarto

To include citations from the references.bib file, use the following syntax:

Inline citation: Gelman and Hill (2006) → Example: Regression models are widely used in statistical analysis @Gelman2006.
Parenthetical citation: (Wickham 2011) → Example: ggplot2 is a powerful tool for data visualization [Wickham, 2011].
Multiple citations: (Wickham 2011; R Core Team 2022) → Example: R is widely used for statistical computing [Wickham, 2011; R Core Team, 2022].

Quarto automatically formats citations according to the bibliography file. Ensure your references are properly formatted to avoid citation errors.

5 HTML-Specific Enhancements

Enable Smooth Scrolling
```
format:
  html:
    smooth-scroll: true
```
Customizing Appearance
- Use Bootstrap classes for styling tables (table-striped, table-hover).
- Apply CSS for additional styling (styles.css).
Interactive Elements
- Use collapse: true in code chunks to hide/show code.
- Use DT for interactive tables (datatable() function). Well suited for dashboards.
- Enable interactive charts with plotly.
- Embed videos using iframe.

6 PDF-Specific Adjustments

Customize LaTeX Formatting

format:
  pdf:
    documentclass: article
    number-sections: true

Adjust Page Layout
- Set margins using geometry.
- Use LaTeX commands in markdown (\textbf{bold text} for bold).
Handling Wide Tables and Figures
- Use out.width="80%" in knitr options for better scaling.
- For multi-page tables, use kableExtra.
- Ensure high-quality figures with dpi=300.

7 Code Chunk Options

Quarto supports several options for customizing code execution. Here are some useful ones:

echo=TRUE: Displays the code in the output.
warning=FALSE: Hides warnings.
message=FALSE: Suppresses messages.
fig.width=6, fig.height=4: Adjusts figure size.
eval=FALSE: Prevents execution of the chunk.
include: true/false: If false, Quarto runs the chunk but hides both the code and the results (useful for setup chunks).

7.1 Rmarkdown syntax

‘{r mtcars-plot1, fig.width=6, fig.height=4, warning=FALSE, message=FALSE}’

Show code

library(ggplot2)
ggplot(mtcars, aes(x = wt, y = mpg)) +
  geom_point() +
  geom_smooth(method = "lm") +
  theme_minimal()

7.2 New quarto syntax

Within the chunk after closing the braces ‘{}’

#| echo: true
#| warning: false
#| message: false
#| fig-width: 6
#| fig-height: 4

Show code

ggplot(mtcars, aes(x = factor(cyl), y = mpg, fill = factor(cyl))) +
  geom_boxplot() +
  theme_classic()

8 Tables with kableExtra

Show code

library(knitr)
library(kableExtra)

mtcars[1:10, 1:5] %>%
  kable("html", caption = "Sample of mtcars dataset") %>%
  kable_styling(bootstrap_options = c("striped", "hover", "condensed"), full_width = FALSE)

Sample of mtcars dataset
	mpg	cyl	disp	hp	drat
Mazda RX4	21.0	6	160.0	110	3.90
Mazda RX4 Wag	21.0	6	160.0	110	3.90
Datsun 710	22.8	4	108.0	93	3.85
Hornet 4 Drive	21.4	6	258.0	110	3.08
Hornet Sportabout	18.7	8	360.0	175	3.15
Valiant	18.1	6	225.0	105	2.76
Duster 360	14.3	8	360.0	245	3.21
Merc 240D	24.4	4	146.7	62	3.69
Merc 230	22.8	4	140.8	95	3.92
Merc 280	19.2	6	167.6	123	3.92

9 Callout Boxes in Quarto

Quarto allows callout boxes to highlight important information:

Note

Note: You can use callout boxes to provide additional explanations.

Tip

Tip: Use {r, cache=TRUE} to speed up rendering by caching code chunks.

Warning

Warning: Be cautious with eval=FALSE as it prevents execution of code chunks.

Important

Important: Always check the output format before finalizing your document.

10 LaTeX Syntax for Statistical Models

Mathematical Notation
- Inline equations: $y = mx + b$
- Block equations: \[ y = \beta_0 + \beta_1 x + \epsilon \]
Fractions and Exponents \[ f(x) = \frac{1}{\sqrt{2\pi\sigma^2}} e^{-\frac{(x-\mu)^2}{2\sigma^2}} \]
Matrix Representation \[ A = \begin{bmatrix} a & b \\ c & d \end{bmatrix} \]
Statistical Distributions \[ X \sim N(\mu, \sigma^2) \]
Summation and Limits \[ \sum_{i=1}^{n} x_i \]

11 Insert images

11.1 From file

11.2 From URL

12 Common Troubleshooting

Issue	Fix
PDF fails to render	Ensure LaTeX is installed (`tinytex::install_tinytex()`)
Images not displaying in PDF	Use absolute paths or `fig.path` in `knitr`
CSS not applying in HTML	Check if `styles.css` is linked correctly
Table formatting issues in PDF	Use kableExtra for better control

13 Final Recommendations

Use .qmd templates to standardize formatting.
Regularly preview outputs to detect formatting issues early.
Experiment with chunk options (e.g., eval=FALSE to disable execution).
Learn basic LaTeX commands to enhance PDF outputs.
Use knitr::include_graphics() for better image handling.

By implementing these tips, you can streamline your workflow and create well-structured, polished documents in Quarto!

Happy coding with Quarto!

14 References

References

Gelman, Andrew, and Jennifer Hill. 2006. Data Analysis Using Regression and Multilevel/Hierarchical Models. New York: Cambridge University Press.

R Core Team. 2022. R: A Language and Environment for Statistical Computing. Vienna, Austria: R Foundation for Statistical Computing. https://www.R-project.org/.

Wickham, Hadley. 2011. “Ggplot2: Elegant Graphics for Data Analysis.” Journal of Computational and Graphical Statistics 20 (1): 3–5. https://doi.org/10.1198/jcgs.2009.07098.

--- title: "Quarto Tips & Tricks" author: "Dr. Adrian Correndo" date: "2026-01-09" categories: [quarto, html, pdf, formatting, data science] format: html: toc: true toc-location: left number-sections: true smooth-scroll: true code-tools: true code-fold: true code-summary: 'Show code' code-link: true bibliography: references.bib link-citations: true reference-section-title: "References" editor: source --- # Introduction Quarto is a powerful tool for creating dynamic documents, and it supports multiple output formats, including **HTML and PDF**. This article presents essential tips and tricks to help you customize and optimize your Quarto documents effectively. # What is Quarto? We are going to explore the new features offered by [Quarto](https://quarto.org) documents (\*.qmd). ![](images/quarto.png) Quarto is a refined version (and successor) of [R-markdown](https://rmarkdown.rstudio.com/). It is an open-source scientific and technical publishing system built on [Pandoc](https://pandoc.org/). It allows to combine R, Python, Julia, and Java (Observable JS) for the design of reports, applications, websites, blogs, scientific publications, and more... # General Formatting Tips - **YAML Configuration:** - Use `title`, `author`, `date`, and `categories` to structure metadata. - Enable **table of contents** (`toc: true`) and **section numbering** (`number-sections: true`). - For citations, link your `bibliography` file and enable `link-citations: true`. - **Organizing Content:** - Use `#` for sections and `##` for subsections. - Inline code: Use `` `code` `` for inline formatting. - Block code: Use triple backticks ```` ```r ```` for code chunks. - Use `::: {.callout-note}` for special notes in Quarto. - Add cross-references using `(@fig:name)` for figures and `(@tbl:name)` for tables. # Citing References in Quarto To include citations from the `references.bib` file, use the following syntax: - **Inline citation:** @Gelman2006 → Example: *Regression models are widely used in statistical analysis* `@Gelman2006`. - **Parenthetical citation:** [@Wickham2011] → Example: ggplot2 is a powerful tool for data visualization \[Wickham, 2011\]. - **Multiple citations:** [@Wickham2011; @RCoreTeam2022] → Example: R is widely used for statistical computing \[Wickham, 2011; R Core Team, 2022\]. Quarto automatically formats citations according to the bibliography file. Ensure your references are properly formatted to avoid citation errors. # HTML-Specific Enhancements - **Enable Smooth Scrolling** ``` yaml format: html: smooth-scroll: true ``` - **Customizing Appearance** - Use Bootstrap classes for styling tables (`table-striped`, `table-hover`). - Apply CSS for additional styling (`styles.css`). - **Interactive Elements** - Use `collapse: true` in code chunks to hide/show code. - Use `{DT}` for interactive tables (`datatable()` function). Well suited for dashboards. - Enable interactive charts with `{plotly}`. - Embed videos using `iframe`. ::: {align="center"} <iframe width="560" height="315" src="https://www.youtube.com/embed/tsuJM_bHSgA" frameborder="0" allowfullscreen> </iframe> ::: # PDF-Specific Adjustments - **Customize LaTeX Formatting** ``` yaml format: pdf: documentclass: article number-sections: true ``` - **Adjust Page Layout** - Set margins using `geometry`. - Use LaTeX commands in markdown (`\textbf{bold text}` for bold). - **Handling Wide Tables and Figures** - Use `out.width="80%"` in `knitr` options for better scaling. - For multi-page tables, use `{kableExtra}`. - Ensure high-quality figures with `dpi=300`. # Code Chunk Options Quarto supports several options for customizing code execution. Here are some useful ones: - `echo=TRUE`: Displays the code in the output. - `warning=FALSE`: Hides warnings. - `message=FALSE`: Suppresses messages. - `fig.width=6, fig.height=4`: Adjusts figure size. - `eval=FALSE`: Prevents execution of the chunk. - `include: true/false`: If `false`, Quarto runs the chunk but hides both the code and the results (useful for setup chunks). ## Rmarkdown syntax '`{r mtcars-plot1, fig.width=6, fig.height=4, warning=FALSE, message=FALSE}`' ```{r mtcars-plot1, fig.width=6, fig.height=4, warning=FALSE, message=FALSE} library(ggplot2) ggplot(mtcars, aes(x = wt, y = mpg)) + geom_point() + geom_smooth(method = "lm") + theme_minimal() ``` ## New quarto syntax Within the chunk after closing the braces '{}' - `#| echo: true` - `#| warning: false` - `#| message: false` - `#| fig-width: 6` - `#| fig-height: 4` ```{r example-chunk-2} #| echo: true #| warning: false #| message: false #| fig-width: 6 #| fig-height: 4 ggplot(mtcars, aes(x = factor(cyl), y = mpg, fill = factor(cyl))) + geom_boxplot() + theme_classic() ``` # Tables with kableExtra ```{r mtcars-kable, results='asis'} library(knitr) library(kableExtra) mtcars[1:10, 1:5] %>% kable("html", caption = "Sample of mtcars dataset") %>% kable_styling(bootstrap_options = c("striped", "hover", "condensed"), full_width = FALSE) ``` # Callout Boxes in Quarto Quarto allows **callout boxes** to highlight important information: ::: callout-note **Note:** You can use callout boxes to provide additional explanations. ::: ::: callout-tip **Tip:** Use `{r, cache=TRUE}` to speed up rendering by caching code chunks. ::: ::: callout-warning **Warning:** Be cautious with `eval=FALSE` as it prevents execution of code chunks. ::: ::: callout-important **Important:** Always check the output format before finalizing your document. ::: # LaTeX Syntax for Statistical Models - **Mathematical Notation** - Inline equations: $y = mx + b$ - Block equations: $$ y = \beta_0 + \beta_1 x + \epsilon $$ - **Fractions and Exponents** $$ f(x) = \frac{1}{\sqrt{2\pi\sigma^2}} e^{-\frac{(x-\mu)^2}{2\sigma^2}} $$ - **Matrix Representation** $$ A = \begin{bmatrix} a & b \\ c & d \end{bmatrix} $$ - **Statistical Distributions** $$ X \sim N(\mu, \sigma^2) $$ - **Summation and Limits** $$ \sum_{i=1}^{n} x_i $$ # Insert images ## From file ![](images/quarto.png) ## From URL ![](https://www.tidyverse.org/images/cover.png) # Common Troubleshooting | Issue | Fix | |------------------------------------------|------------------------------| | PDF fails to render | Ensure LaTeX is installed (`tinytex::install_tinytex()`) | | Images not displaying in PDF | Use absolute paths or `fig.path` in `knitr` | | CSS not applying in HTML | Check if `styles.css` is linked correctly | | Table formatting issues in PDF | Use `{kableExtra}` for better control | # Final Recommendations - **Use `.qmd` templates** to standardize formatting. - **Regularly preview outputs** to detect formatting issues early. - **Experiment with chunk options** (e.g., `eval=FALSE` to disable execution). - **Learn basic LaTeX commands** to enhance PDF outputs. - **Use `knitr::include_graphics()`** for better image handling. By implementing these tips, you can streamline your workflow and create well-structured, polished documents in Quarto! ------------------------------------------------------------------------ *Happy coding with Quarto!* # References