quarto-authoring

name: quarto-authoring description: > Comprehensive guidance for Quarto document authoring and R Markdown migration. Use this skill when: (1) Writing new Quarto documents (.qmd) with best practices, (2) Converting R Markdown (.Rmd) documents to Quarto, (3) Migrating bookdown, blogdown, xaringan, or distill projects to Quarto, (4) Understanding Quarto's code cell syntax with hashpipe (#|) options, (5) Setting up cross-references for figures, tables, sections, and equations, (6) Using Quarto-specific markdown features like callouts, divs, and spans, (7) Configuring YAML front matter for documents and projects, (8) Finding and using Quarto extensions.

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.md

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

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

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

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

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

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

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

Task: Create tables Use: references/tables.md

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

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

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

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

Task: Use shortcodes Use: references/shortcodes.md

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

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

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

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

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

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:

YAML Front Matter: Metadata and configuration at the top, enclosed by ---.
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.md

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."
#| fig-width: 8
#| fig-height: 6

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.md

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

Example:

::: {#fig-plot}
A plot.

A caption for the plot.
:::

See @fig-plot for the results.

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

See @fig-plot for the results.

Details: references/cross-references.md

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.md

Figures

Basic figure with caption:

![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.md

Tables

Pipe table with caption:

::: {#tbl-example}

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

Table caption.
:::

Details: references/tables.md

Citations

Basic syntax:

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

Configure in YAML:

bibliography: references.bib
csl: apa.csl

Details: references/citations.md

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

Reference Files

references/code-cells.md - Hashpipe syntax, execution options, code display
references/cross-references.md - Labels, prefixes, all reference types
references/figures.md - Figures, subfigures, layouts, lightbox
references/tables.md - Pipe tables, grid tables, styling
references/citations.md - Bibliography, CSL, footnotes
references/callouts.md - Callout types, appearance, collapsible
references/diagrams.md - Mermaid, Graphviz/DOT
references/layout.md - Column classes, margin content
references/shortcodes.md - Built-in shortcodes
references/conditional-content.md - Format-specific content
references/divs-and-spans.md - Fenced divs, spans, raw blocks
references/yaml-front-matter.md - Document and project YAML
references/extensions.md - Using and finding extensions
references/markdown-linting.md - Markdown linting rules for Quarto

Conversion Guides

references/conversion-rmarkdown.md - R Markdown to Quarto
references/conversion-bookdown.md - bookdown to Quarto
references/conversion-xaringan.md - xaringan to RevealJS
references/conversion-distill.md - distill to Quarto
references/conversion-blogdown.md - blogdown to Quarto website