Quarto Authoring

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

Access environment variables:

Audit 0.4.1 · source sha babb6bf12fac · 17 Oct 2026Report an issue or request a re-scan

• Publisherposit-dev GitHub organizationOwner of the repository this skill is read from
• Source folderposit-dev/skills/quarto/quarto-authoringThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdictbabb6bf12facA new audit runs when the source changes
• Repository statusNot archivedLast push 1 day ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Use when the user is explicitly working with Quarto, .qmd files, _quarto.yml, Quarto projects, or Quarto features such as callouts, cross-references, citations, Mermaid diagrams, extensions, websites, books,…

---
name: quarto-authoring
description: Use when the user is explicitly working with Quarto, .qmd files, _quarto.yml, Quarto projects, or Quarto features such as callouts, cross-references, citations, Mermaid diagrams, extensions, websites, books, presentations, and reports. Also use for explicit migration from or comparison with R Markdown, bookdown, blogdown, xaringan, distill, or Jupyter notebooks to Quarto. Do not use for general R Markdown or related-format questions unless Quarto or migration to Quarto is explicitly mentioned.
metadata:
  author: Mickaël Canouil (@mcanouil)
  version: "1.4"
license: MIT
---

# Quarto Authoring

> This skill is based on Quarto CLI v1.9.36 (2026-03-24).

## When to Use What

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

Task: Add cross-references
Use: [references/cross-references.md](references/cross-references.md)

Task: Configure code cells
Use: [references/code-cells.md](references/code-cells.md)

Task: Add figures with captions
Use: [references/figures.md](references/figures.md)

Task: Create tables
Use: [references/tables.md](references/tables.md)

Task: Add citations and bibliography
Use: [references/citations.md](references/citations.md)

Task: Add callout blocks
Use: [references/callouts.md](references/callouts.md)

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

Task: Control page layout
Use: [references/layout.md](references/layout.md)

Task: Use shortcodes
Use: [references/shortcodes.md](references/shortcodes.md)

Task: Add conditional content
Use: [references/conditional-content.md](references/conditional-content.md)

Task: Use divs and spans
Use: [references/divs-and-spans.md](references/divs-and-spans.md)

Task: Configure YAML front matter
Use: [references/yaml-front-matter.md](references/yaml-front-matter.md)

Task: Find and use extensions
Use: [references/extensions.md](references/extensions.md)

Task: Apply markdown linting rules
Use: [references/markdown-linting.md](references/markdown-linting.md)

Task: Choose or configure a compute engine (knitr, jupyter, julia)
Use: [references/engines.md](references/engines.md)

### Migration (only when converting an existing project)

Do NOT read these references when writing new Quarto documents.
Only read the one matching the source format when the user explicitly asks to convert or migrate an existing project.

- R Markdown (.Rmd) to Quarto: [references/conversion-rmarkdown.md](references/conversion-rmarkdown.md)
- bookdown project: [references/conversion-bookdown.md](references/conversion-bookdown.md)
- xaringan slides: [references/conversion-xaringan.md](references/conversion-xaringan.md)
- distill article: [references/conversion-distill.md](references/conversion-distill.md)
- blogdown site: [references/conversion-blogdown.md](references/conversion-blogdown.md)
- Jupyter notebook (.ipynb) to/from Quarto: [references/conversion-jupyter.md](references/conversion-jupyter.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:

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:

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

Spans use bracketed syntax:

```markdown
This is [important text]{.highlight}.
```

Details: [references/divs-and-spans.md](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, Julia: `#|`
- Mermaid: `%%|`
- Graphviz/DOT: `//|`

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

# code that produces a figure
```
````

Set document-level defaults in YAML front matter:

```yaml
execute:
  echo: false
  warning: false
```

**Caching — critical engine difference:** Only suggest `#| cache: true` for R code cells (knitr engine).
Never suggest it for other language cells — it does not work and will be silently ignored.
The only correct approach is `execute: cache: true` in the top-level YAML front matter when using engines other than `knitr`.
Python/Jupyter requires `jupyter-cache` (`pip install jupyter-cache`):

```yaml
execute:
  cache: true
```

Details: [references/code-cells.md](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
```{language}
#| label: fig-plot
#| fig-cap: "A caption for the plot."

# code that produces a figure
```

See @fig-plot for the results.
````

Details: [references/cross-references.md](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](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](references/figures.md)

### Tables

```markdow

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/posit-dev/skills
git -C skills checkout babb6bf12fac

Works in

1. 2026-10-17
   ✓SAFE B 89 / 100

   first audit · source babb6bf12fac

Questions about Quarto Authoring

• github.com/posit-dev/skills/tree/main/quarto/quarto-authoring — the audited source at commit babb6bf12fac and every finding aboveObserved · 17 Oct 2026

Spotted something wrong? Report a correction · Methodology