---
name: create-quarto-report-7c95fb8b5ff1
description: >
  Create a Quarto document for reproducible reports, presentations, or
  websites. Covers YAML configuration, code chunk options, output
  formats, cross-references, and rendering. Use when creating a
  reproducible analysis report, building a presentation with embedded
  code, generating HTML, PDF, or Word documents from code, or migrating
  an existing R Markdown document to Quarto.
license: MIT
allowed-tools: Read Write Edit Bash Grep Glob
metadata:
  author: Philipp Thoss
  version: "1.0"
  domain: reporting
  complexity: basic
  language: R
  tags: quarto, report, reproducible, rmarkdown, publishing
---

# Create Quarto Report

Set up and write a reproducible Quarto document for analysis reports, presentations, or websites.

## When to Use

- Creating a reproducible analysis report
- Building a presentation with embedded code
- Generating HTML, PDF, or Word documents from code
- Migrating from R Markdown to Quarto

## Inputs

- **Required**: Report topic and target audience
- **Required**: Output format (html, pdf, docx, revealjs)
- **Optional**: Data sources and analysis code
- **Optional**: Citation bibliography (.bib file)

## Procedure

### Step 1: Create Quarto Document

Create `report.qmd`:

```yaml
---
title: "Analysis Report"
author: "Author Name"
date: today
format:
  html:
    toc: true
    toc-depth: 3
    code-fold: true
    theme: cosmo
    self-contained: true
execute:
  echo: true
  warning: false
  message: false
bibliography: references.bib
---
```

**Expected:** File `report.qmd` exists with valid YAML frontmatter including title, author, date, format configuration, and execution options.

**On failure:** Validate the YAML header by checking for matching `---` delimiters and correct indentation. Ensure `format:` key matches one of the supported Quarto output formats (`html`, `pdf`, `docx`, `revealjs`).

### Step 2: Write Content with Code Chunks

````markdown
## Introduction

This report analyzes the relationship between variables X and Y.

## Data

```{r}
#| label: load-data
library(dplyr)
library(ggplot2)

data <- read.csv("data.csv")
glimpse(data)
```

## Analysis

```{r}
#| label: fig-scatter
#| fig-cap: "Scatter plot of X vs Y"
#| fig-width: 8
#| fig-height: 6

ggplot(data, aes(x = x_var, y = y_var)) +
  geom_point(alpha = 0.6) +
  geom_smooth(method = "lm") +
  theme_minimal()
```

As shown in @fig-scatter, there is a positive relationship.

## Results

```{r}
#| label: tbl-summary
#| tbl-cap: "Summary statistics"

data |>
  summarise(
    mean_x = mean(x_var),
    sd_x = sd(x_var),
    mean_y = mean(y_var),
    sd_y = sd(y_var)
  ) |>
  knitr::kable(digits = 2)
```

See @tbl-summary for descriptive statistics.
````

**Expected:** Content sections contain properly formatted code chunks with `{r}` language identifier and `#|` chunk options for labels, captions, and dimensions.

**On failure:** Verify code chunks use the ```` ```{r} ```` syntax (not inline backticks), that `#|` options are inside the chunk (not in the YAML header), and that label prefixes match cross-reference types (`fig-` for figures, `tbl-` for tables).

### Step 3: Configure Chunk Options

Common chunk-level options (use `#|` syntax):

```text
#| label: chunk-name        # Required for cross-references
#| echo: false               # Hide code
#| eval: false               # Show but don't run
#| output: false             # Run but hide output
#| fig-width: 8              # Figure dimensions
#| fig-height: 6
#| fig-cap: "Caption text"   # Enable @fig-name references
#| tbl-cap: "Caption text"   # Enable @tbl-name references
#| cache: true               # Cache expensive computations
```

**Expected:** Chunk options are applied at the chunk level using `#|` syntax, and labels follow naming conventions required for cross-referencing.

**On failure:** Ensure chunk options use `#|` syntax (Quarto-native), not the legacy `{r, option=value}` R Markdown syntax. Verify that label names contain only alphanumeric characters and hyphens.

### Step 4: Add Cross-References and Citations

```markdown
See @fig-scatter for the visualization and @tbl-summary for statistics.

This approach follows @smith2023 methodology.

::: {#fig-combined layout-ncol=2}
![Plot A](plot_a.png){#fig-plotA}
![Plot B](plot_b.png){#fig-plotB}

Combined figure caption
:::
```

**Expected:** Cross-references (`@fig-name`, `@tbl-name`) resolve to the correct figures and tables, and citations (`@key`) match entries in the `.bib` file.

**On failure:** Verify that referenced labels exist in code chunks with the correct prefix (`fig-`, `tbl-`). For citations, check that `.bib` keys match exactly (case-sensitive) and that `bibliography:` is set in the YAML header.

### Step 5: Render the Document

```bash
quarto render report.qmd

# Specific format
quarto render report.qmd --to pdf
quarto render report.qmd --to docx

# Preview with live reload
quarto preview report.qmd
```

**Expected:** Output file generated in the specified format.

**On failure:**
- Missing quarto: Install from https://quarto.org/docs/get-started/
- PDF errors: Install TinyTeX with `quarto install tinytex`
- R package errors: Ensure all packages are installed

### Step 6: Multi-Format Output

```yaml
format:
  html:
    toc: true
    theme: cosmo
  pdf:
    documentclass: article
    geometry: margin=1in
  docx:
    reference-doc: template.docx
```

Render all formats: `quarto render report.qmd`

**Expected:** All specified output formats generate successfully, each with correct styling and layout for the target format.

**On failure:** If one format fails while others succeed, check format-specific requirements: PDF needs a LaTeX engine (install with `quarto install tinytex`), DOCX needs a valid reference template if specified, and format-specific YAML options must be correctly nested under each format key.

## Validation

- [ ] Document renders without errors
- [ ] All code chunks execute correctly
- [ ] Cross-references resolve (figures, tables, citations)
- [ ] Table of contents is accurate
- [ ] Output format is appropriate for the audience

## Common Pitfalls

- **Missing label prefix**: Cross-referenceable figures need `fig-` prefix in label, tables need `tbl-`
- **Cache invalidation**: Cached chunks won't re-run when upstream data changes. Delete `_cache/` to force.
- **PDF without LaTeX**: Install TinyTeX or use `format: pdf` with `pdf-engine: weasyprint` for CSS-based PDF
- **R Markdown syntax in Quarto**: Use `#|` chunk options instead of `{r, echo=FALSE}` style

## Related Skills

- `format-apa-report` - APA-formatted academic reports
- `build-parameterized-report` - parameterized multi-report generation
- `generate-statistical-tables` - publication-ready tables
- `write-vignette` - Quarto vignettes in R packages


---
Source attribution: pjt222
Original project: https://github.com/pjt222/agent-almanac/blob/cabe7834815765f915822ba1f361aa4623398871/skills/create-quarto-report/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Dave AI.

## Upstream license notice

MIT License

Copyright (c) 2025 Development Guides Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


# Dave AI resource metadata

Creator / publisher: pjt222
Original project: https://github.com/pjt222/agent-almanac/blob/cabe7834815765f915822ba1f361aa4623398871/skills/create-quarto-report/SKILL.md
Attribution basis: Source repository record

Fields of work: Data & Analytics, Marketing, Product Management
Roles: Content Marketer, Data Analyst, Product Manager
Specialties: API
Tools: Quarto
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: 696132b293877e2fad144e9fac1bb67c5dd9109616fb8557f07d019d755f5b8c