Quarto Authoring

Quarto Authoring

This skill is based on Quarto CLI v1.8.26.

When to Use What

Task: Write a new Quarto document Use: Follow "QMD Essentials" below, then see specific reference files

Task: Convert R Markdown to Quarto Use: references/conversion-rmarkdown.rst

Task: Migrate bookdown project Use: references/conversion-bookdown.rst

Task: Migrate xaringan slides Use: references/conversion-xaringan.rst

Task: Migrate distill article Use: references/conversion-distill.rst

Task: Migrate blogdown site Use: references/conversion-blogdown.rst

Task: Add cross-references Use: references/cross-references.rst

Task: Configure code cells Use: references/code-cells.rst

Task: Add figures with captions Use: references/figures.rst

Task: Create tables Use: references/tables.rst

Task: Add citations and bibliography Use: references/citations.rst

Task: Add callout blocks Use: references/callouts.rst

Task: Add diagrams (Mermaid, Graphviz) Use: references/diagrams.rst

Task: Control page layout Use: references/layout.rst

Task: Use shortcodes Use: references/shortcodes.rst

Task: Add conditional content Use: references/conditional-content.rst

Task: Use divs and spans Use: references/divs-and-spans.rst

Task: Configure YAML front matter Use: references/yaml-front-matter.rst

Task: Find and use extensions Use: references/extensions.rst

Task: Apply markdown linting rules Use: references/markdown-linting.rst

QMD Essentials

Basic Document Structure

---
title: "Document Title"
author: "Author Name"
date: today
format: html
---

Content goes here.

A Quarto document consists of two main parts:

1. YAML Front Matter: Metadata and configuration at the top, enclosed by ---.
2. Markdown Content: Main body using standard markdown syntax.

Divs and Spans

Divs use fenced syntax with three colons:

::: {.class-name}
Content inside the div.
:::

Spans use bracketed syntax:

This is [important text]{.highlight}.

Details: references/divs-and-spans.rst

Code Cell Options Syntax

A code cell starts with triple backticks and a language identifier between curly braces. Code cells are code blocks that can be executed to produce output.

Quarto uses the language's comment symbol + | for cell options. Options use dashes, not dots (e.g., fig-cap not fig.cap).

• R, Python: #|
• Mermaid: %%|
• Graphviz/DOT: //|

```{r}
#| label: fig-example
#| echo: false
#| fig-cap: "A scatter plot example."

plot(x, y)
```

Common execution options:

Option	Description	Values
eval	Evaluate code	true, false
echo	Show code	true, false, fenced
output	Include output	true, false, asis
warning	Show warnings	true, false
error	Show errors	true, false
include	Include in output	true, false

Set document-level defaults in YAML front matter:

execute:
  echo: false
  warning: false

Details: references/code-cells.rst

Cross-References

Labels must start with a type prefix. Reference with @:

• Figure: fig- prefix, e.g., #| label: fig-plot → @fig-plot
• Table: tbl- prefix, e.g., #| label: tbl-data → @tbl-data
• Section: sec- prefix, e.g., {#sec-intro} → @sec-intro
• Equation: eq- prefix, e.g., {#eq-model} → @eq-model

```{r}
#| label: fig-plot
#| fig-cap: "A caption for the plot."
plot(1)
```

See @fig-plot for the results.

Details: references/cross-references.rst

Callout Blocks

Five types: note, warning, important, tip, caution.

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

::: {.callout-warning}

## Custom Title

This is a warning with a custom title.

:::

Details: references/callouts.rst

Figures

![Caption text](image.png){#fig-name fig-alt="Alt text"}

Subfigures:

::: {#fig-group layout-ncol=2}
![Sub caption 1](image1.png){#fig-sub1}

![Sub caption 2](image2.png){#fig-sub2}

Main caption for the group.
:::

Details: references/figures.rst

Tables

::: {#tbl-example}

| Column 1 | Column 2 |
| -------- | -------- |
| Data 1   | Data 2   |

Table caption.
:::

Details: references/tables.rst

Citations

According to @smith2020, the results show...
Multiple citations [@smith2020; @jones2021].

Configure in YAML:

bibliography: references.bib
csl: apa.csl

Details: references/citations.rst

Common Workflows

Creating an HTML Document

title: "My Report"
author: "Your Name"
date: today
format:
  html:
    toc: true
    code-fold: true
    theme: cosmo

Creating a PDF Document

title: "My Report"
format:
  pdf:
    documentclass: article
    papersize: a4

Creating a RevealJS Presentation

---
title: "My Presentation"
format: revealjs
---

## First Slide

Content here.

## Second Slide

More content.

Setting Up a Quarto Project

Create _quarto.yml in the project root:

project:
  type: website

website:
  title: "My Site"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - href: about.qmd
        text: About

format:
  html:
    theme: cosmo

Resources

• Quarto Documentation
• Quarto Guide

• Quarto Extensions
• Community Extensions List