3 Creating a Quarto Book Based on R Markdown

3.1 Overview: Quarto and R Markdown

Quarto renders books using Pandoc to transform Markdown. This allows for a streamlined conversion from R Markdown to Quarto. Click here to see more.

3.2 From R Markdown to Quarto

Suppose you already have content organized in R Markdown files and want to convert and gather them to create a book, website, or other output using Quart. Small changes in the syntax and directory structure allow for this conversion.

3.2.1 Convert `.md` Files to `.qmd` Files

First, change the file extensions from .Rmd to .qmd. Then, change the YAML headers:

---
title:"Chapter Title Here"
format: html
---

Ensure the folder contains index.qmd and _quarto.yml (see Chapter 2). All the .qmd files should be listed in the chapters of _quarto.yml. Render the book to preview your converted content.

3.2.2 Syntax

Quarto can read the majority of R Markdown syntax directly. There are some minor differences. We list them below.

3.2.2.1 Code Chunks

Quarto can read R Markdown’s code chunk syntax, but it also has its own style.

Markdown:

{r, fig.cap = "", fig.alt= ""}
plot()

Quarto:

{r,eval= FALSE}
#| label: Label
#| fig-cap: Caption
#| fig-alt: Alternative text
plot()

You can copy Markdown code chunks directly to .qmd files without changing them to the Quarto style. However, do not mix styles in the same file. If there is a mixture of styles, Quarto will only read the ones with Quarto syntax. Click here to learn more about Quarto’s Markdown basics.

3.2.2.2 LaTeX

It is possible to use Quarto to render a PDF file with LaTeX syntax. Quarto uses a LaTeX engine to output PDF format file.

Math

The LaTeX mathematical environments and syntax are supported in Quarto. You can copy LaTeX math code into a .qmd file.

LaTeX Text Commands

LaTeX document structure or formatting control commands are not valid in Quarto’s markdown body when converting to HTML. The reason is that Quarto is based on Pandoc Markdown, and text styles are recommended to use Markdown syntax. For example, do not use:\textbf{} or \textit{} in the main text. Instead, use Markdown syntax: **bold** or *italic*.

References

Be careful with the reference syntax. When you make ref, you have to rewrite them in a Quarto syntax instead of LaTeX reference commands to make sure it referred correctly. (Is in ECON470 only have 2 eqref?)

This table shows the relative reference commands between LaTeX and Quarto:

LaTeX	Quarto	Notes
`\label{eq:foo}`	`{#eq-foo}` or `\label{eqfoo}`	Add a label to the formula at the end of the formula block or within the equation.
`\eqref{eq:foo}`	`@eq-foo`	Equation number with parentheses.
Equation environment	`$$ E = mc^2 $$ {#eq-emc2}`	-
`\ref{fig:bar}`	`@fig-bar`	Reference a figure.
Figure environment	`![Caption](figure.png){#fig-energy}`	-
`\ref{tbl:baz}`	`@tbl-baz`	Reference a table.
Table environment	`Caption {#tbl-sample}`	-
`\ref{sec:qux}`	`@sec-qux`	Referece a section.
`\section{Methods}`	`## Methods {#sec-methods}`	-
`\cite{key}`	`[@key]` or `@key`	Citations of literature should be preceded by `@` or `[@]` (in parentheses).
`\autoref{fig:bar}`/`\ref{fig:bar}`	Figure `@fig-bar`	Automatically prefix the name by directly writing Figure followed by `@`.
`\nameref{sec:qux}`	`\@ref(sec-qux)`	In Pandoc, you can use `\@ref()` to get a hyperlink and title text (optional).
`\pageref{}`	-	Quarto does not support page number references.

Click here to see more about in-text references in Quarto.