quarto-authoring

Original：🇺🇸 English

Translated

Writing and authoring Quarto documents (.qmd), including code cell options, figure and table captions, cross-references, callout blocks (notes, warnings, tips), citations and bibliography, page layout and columns, Mermaid diagrams, YAML metadata configuration, and Quarto extensions. Also covers converting and migrating R Markdown (.Rmd), bookdown, blogdown, xaringan, and distill projects to Quarto, and creating Quarto websites, books, presentations, and reports.

2installs

Sourceposit-dev/skills

Added on2026-02-24

NPX Install

npx skill4agent add posit-dev/skills quarto-authoring

SKILL.md Content

View Translation Comparison →

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

markdown

---
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:

markdown

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

Spans use bracketed syntax:

markdown

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:
```
//|
```

markdown

```{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:

yaml

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
```

markdown

```{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

.

markdown

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

::: {.callout-warning}

## Custom Title

This is a warning with a custom title.

:::

Details: references/callouts.md

Figures

markdown

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

Subfigures:

markdown

::: {#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

markdown

::: {#tbl-example}

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

Table caption.
:::

Details: references/tables.md

Citations

markdown

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

Configure in YAML:

yaml

bibliography: references.bib
csl: apa.csl

Details: references/citations.md

Common Workflows

Creating an HTML Document

yaml

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

Creating a PDF Document

yaml

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

Creating a RevealJS Presentation

markdown

---
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:

yaml

project:
  type: website

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

format:
  html:
    theme: cosmo

quarto-authoring

NPX Install

Tags

SKILL.md Content

Quarto Authoring

When to Use What

QMD Essentials

Basic Document Structure

Divs and Spans

Code Cell Options Syntax

Cross-References

Callout Blocks

Figures

Tables

Citations

Common Workflows

Creating an HTML Document

Creating a PDF Document

Creating a RevealJS Presentation

Setting Up a Quarto Project

Resources