Converting R Markdown to Quarto

February 20, 2026 · View on GitHub

Guide for converting R Markdown (.Rmd) documents to Quarto (.qmd).

Overview

Most R Markdown documents can be rendered by Quarto with minimal changes. The main differences are:

YAML structure (output → format)
Chunk options (inline → hashpipe)
Option naming (dots → dashes)

Quick Start

Rename File

mv document.Rmd document.qmd

Update YAML

R Markdown

output: html_document

Quarto

format: html

Update Chunk Options

R Markdown

```{r, echo=TRUE, fig.cap="My figure"}
plot(1:10)
```

Quarto

```{r}
#| echo: true
#| fig-cap: "My figure"

plot(1:10)
```

Format Mapping

R Markdown	Quarto
`html_document`	`html`
`pdf_document`	`pdf`
`word_document`	`docx`
`github_document`	`gfm`
`beamer_presentation`	`beamer`
`ioslides_presentation`	`revealjs`
`slidy_presentation`	`revealjs`
`powerpoint_presentation`	`pptx`

YAML Conversion

Basic Document

R Markdown

title: "My Document"
author: "Jane Doe"
date: "2024-01-15"
output:
  html_document:
    toc: true
    toc_float: true
    code_folding: show

Quarto

title: "My Document"
author: "Jane Doe"
date: 2024-01-15
format:
  html:
    toc: true
    toc-location: left
    code-fold: show

Multiple Outputs

R Markdown

output:
  html_document:
    toc: true
  pdf_document:
    toc: true

Quarto

format:
  html:
    toc: true
  pdf:
    toc: true

Common Options

R Markdown	Quarto
`toc: true`	`toc: true`
`toc_float: true`	`toc-location: left`
`toc_depth: 3`	`toc-depth: 3`
`number_sections: true`	`number-sections: true`
`code_folding: show`	`code-fold: show`
`theme: cosmo`	`theme: cosmo`
`highlight: tango`	`highlight-style: tango`
`fig_width: 8`	`fig-width: 8`
`fig_height: 6`	`fig-height: 6`
`df_print: kable`	(use knitr::kable or gt)

Chunk Options

Syntax Change

Options move inside the code block with #| prefix:

R Markdown

```{r my-chunk, echo=FALSE, fig.cap="Caption", fig.width=8}
plot(1:10)
```

Quarto

```{r}
#| label: my-chunk
#| echo: false
#| fig-cap: "Caption"
#| fig-width: 8

plot(1:10)
```

Option Naming: Dots to Dashes

R Markdown	Quarto
`fig.cap`	`fig-cap`
`fig.width`	`fig-width`
`fig.height`	`fig-height`
`fig.align`	`fig-align`
`fig.alt`	`fig-alt`
`out.width`	(use `fig-width` or CSS)
`results`	`output`
`message`	`message`
`warning`	`warning`
`include`	`include`

Results Option

R Markdown

results='asis'
results='hide'
results='markup'

Quarto

#| output: asis
#| output: false
#| output: true

Setup Chunks

R Markdown

```{r setup, include=FALSE}
knitr::opts_chunk$set(
  echo = TRUE,
  warning = FALSE,
  message = FALSE,
  fig.width = 8,
  fig.height = 6
)
```

Quarto

Use YAML instead:

execute:
  echo: true
  warning: false
  message: false
format:
  html:
    fig-width: 8
    fig-height: 6

Or keep setup chunk for R-specific options.

Inline Code

R Markdown

The value is `r mean(x)`.

Quarto

Same syntax works:

The value is `r mean(x)`.

Or with explicit language:

The value is `{r} mean(x)`.

Cross-References

Figures

R Markdown (requires bookdown)

```{r my-fig, fig.cap="Caption"}
plot(1:10)
```

See Figure \@ref(fig:my-fig).

Quarto

```{r}
#| label: fig-myplot
#| fig-cap: "Caption"

plot(1:10)
```

See @fig-myplot.

Tables

R Markdown (requires bookdown)

```{r my-table}
knitr::kable(mtcars[1:5,], caption = "My table")
```

See Table \@ref(tab:my-table).

Quarto

```{r}
#| label: tbl-mydata
#| tbl-cap: "My table"

knitr::kable(mtcars[1:5,])
```

See @tbl-mydata.

Note: Quarto uses tbl- prefix (not tab-).

Quarto doesn't require rmarkdown or knitr, but knitr remains useful for tables and chunk processing. Most R Markdown features (knitr::kable(), knitr::include_graphics()) work in Quarto without changes.

Note: Quarto can render .Rmd files directly (quarto render document.Rmd) using R Markdown compatibility mode, which allows incremental migration.

Common Issues

Output Not Found

ERROR: Unknown format

Check format name mapping (e.g., html_document → html).

Figure Not Appearing

Ensure label starts with fig- for cross-references.

Table Cross-Reference Fails

Use tbl- prefix (not tab-).

Chunk Options Ignored

Verify #| syntax and dashes (not dots).