Converting bookdown to Quarto

February 20, 2026 · View on GitHub

Guide for converting bookdown projects to Quarto book format.

Overview

Key differences:

Configuration file: _bookdown.yml → _quarto.yml
Cross-references: \@ref() → @
Chapter organization
Theorem environments

Quick Start

1. Create Quarto Config

Replace _bookdown.yml with _quarto.yml:

project:
  type: book

book:
  title: "My Book"
  author: "Author Name"
  chapters:
    - index.qmd
    - chapter1.qmd
    - chapter2.qmd

format:
  html:
    theme: cosmo
  pdf:
    documentclass: book

2. Rename Files

for f in *.Rmd; do mv "$f" "${f%.Rmd}.qmd"; done

3. Update Cross-References

Bookdown

See Figure \@ref(fig:myplot)
See Table \@ref(tab:mytable)

Quarto

See @fig-myplot
See @tbl-mytable

Configuration Mapping

bookdown (`_bookdown.yml`)

book_filename: "my-book"
output_dir: "docs"
delete_merged_file: true
language:
  ui:
    chapter_name: "Chapter "
rmd_files:
  - index.Rmd
  - 01-intro.Rmd
  - 02-methods.Rmd
  - 03-results.Rmd
  - references.Rmd

Quarto (`_quarto.yml`)

project:
  type: book
  output-dir: docs

book:
  title: "My Book"
  author: "Author Name"
  date: today
  chapters:
    - index.qmd
    - intro.qmd
    - methods.qmd
    - results.qmd
  appendices:
    - references.qmd

format:
  html:
    theme: cosmo
  pdf:
    documentclass: book

Chapter Organization

With Parts

book:
  chapters:
    - index.qmd
    - part: "Part I: Foundation"
      chapters:
        - basics.qmd
        - setup.qmd
    - part: "Part II: Advanced"
      chapters:
        - advanced1.qmd
        - advanced2.qmd
  appendices:
    - appendix.qmd

Numbered vs Unnumbered

Add {.unnumbered} to exclude from numbering:

# Preface {.unnumbered}

Cross-Reference Conversion

Figures

bookdown

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

See Figure \@ref(fig:myplot).

Quarto

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

plot(1:10)
```

See @fig-myplot.

Tables

bookdown

```{r mytable}
knitr::kable(head(iris), caption = "Iris data")
```

See Table \@ref(tab:mytable).

Quarto

```{r}
#| label: tbl-iris
#| tbl-cap: "Iris data"

knitr::kable(head(iris))
```

See @tbl-iris.

Note: Quarto uses tbl- not tab-.

Equations

bookdown

# bookdown
\begin{equation}
y = mx + b (\#eq:line)
\end{equation}
See Equation \@ref(eq:line).

Quarto

$$
y = mx + b
$$ {#eq-line}

See @eq-line.

Sections

bookdown

# Introduction {#intro}

See Section \@ref(intro).

Quarto

# Introduction {#sec-intro}

See @sec-intro.

Theorems

bookdown

```{theorem, name="Pythagorean"}
For a right triangle, $a^2 + b^2 = c^2$.
```

See Theorem \@ref(thm:pythagorean).

Quarto

::: {#thm-pythagorean}

## Pythagorean Theorem

For a right triangle, $a^2 + b^2 = c^2$.
:::

See @thm-pythagorean.

Theorem Environments

bookdown

```{theorem, label="main", name="Main Theorem"}
Statement here.
```

```{lemma}
Lemma statement.
```

```{proof}
Proof here.
```

Quarto

::: {#thm-main}

## Main Theorem

Statement here.

:::

::: {#lem-helper}

## Helper Lemma

Lemma statement.

:::

::: {.proof}
Proof here.
:::

Supported types: thm, lem, cor, prp, cnj, def, exm, exr.

Custom Blocks

bookdown

```{block, type='rmdnote'}
This is a note.
```

Quarto

::: {.callout-note}
This is a note.
:::

Output Formats

bookdown

output:
  bookdown::gitbook:
    css: style.css
  bookdown::pdf_book:
    includes:
      in_header: preamble.tex

Quarto

format:
  html:
    theme: cosmo
    css: style.css
  pdf:
    documentclass: book
    include-in-header: preamble.tex

Format Mapping

bookdown	Quarto
`gitbook`	`html`
`pdf_book`	`pdf`
`epub_book`	`epub`
`word_document2`	`docx`

Bibliography

bookdown

# _bookdown.yml
bibliography: [book.bib, packages.bib]

Quarto

In _quarto.yml:

book:
  bibliography: references.bib

Or in individual files:

bibliography: references.bib

Custom Styling

HTML

format:
  html:
    theme:
      - cosmo
      - custom.scss
    css: styles.css

PDF

format:
  pdf:
    documentclass: book
    include-in-header: preamble.tex

Common Issues

Chapters Not Found

Check file names in _quarto.yml match actual files.

Cross-Reference Not Working

Ensure:

Label has correct prefix (fig-, tbl-, etc.)
Reference uses @ syntax

Theorem Numbering Wrong

Check theorem IDs are unique and properly formatted.