name: quarto
description: This skill should be used when users need to create, configure, or render Quarto documents (.qmd files). Use this skill for generating reports, analysis documents, or presentations with HTML or Typst output formats, integrating code chunks (Python, R, Stata), and troubleshooting rendering issues.
Quarto Document Generation Skill
Contents
When to Use This Skill
| Task |
Use This Skill |
| Create .qmd documents |
Yes |
| Configure HTML/Typst output |
Yes |
| Embed Python/R/Stata code |
Yes |
| Set up Quarto projects |
Yes |
| Debug rendering issues |
Yes |
| Generate reports from templates |
Yes |
Quick Start
Basic Document Structure
---
title: "Document Title"
author: "Author Name"
date: "2025-01-05"
format:
html:
toc: true
code-fold: true
---
# Introduction
Content here...
```{python}
# Code chunk
import pandas as pd
Render Commands
quarto render document.qmd # Default format
quarto render document.qmd --to html
quarto render document.qmd --to typst
quarto preview document.qmd # Live preview
Output Formats
HTML vs Typst
| Feature |
HTML |
Typst |
| Best for |
Web, interactive |
Print, PDF |
| Code folding |
Yes |
No |
| Embedded resources |
Yes |
N/A |
| Math rendering |
KaTeX/MathJax |
Native |
| Custom fonts |
CSS |
Direct |
HTML Configuration
format:
html:
toc: true
toc-depth: 3
code-fold: true
code-tools: true
embed-resources: true
theme: cosmo
Typst Configuration
format:
typst:
toc: true
number-sections: true
papersize: us-letter
margin:
x: 1.25in
y: 1.25in
fontsize: 11pt
Multiple Formats
format:
html:
toc: true
typst:
toc: true
Code Chunks
Cell Options
| Option |
Effect |
echo: false |
Hide code, show output |
eval: false |
Show code, don't run |
output: false |
Hide all output |
warning: false |
Suppress warnings |
include: false |
Run but show nothing |
error: true |
Show errors, don't fail |
cache: true |
Cache results |
Python Example
```{python}
#| label: fig-plot
#| fig-cap: "My Figure"
#| echo: false
import matplotlib.pyplot as plt
plt.plot([1, 2, 3], [1, 4, 9])
plt.show()
```
Cross-References
See @fig-plot for visualization.
Results in @tbl-results.
Methods in @sec-methods.
## Methods {#sec-methods}
```{python}
#| label: fig-plot
#| fig-cap: "My plot"
```
Document Workflow
1. Create Document
# Using template script
uv run python .claude/skills/quarto/scripts/create_quarto.py \
--output report.qmd \
--title "My Report" \
--format html \
--template analysis
Template types: analysis, report, presentation, article
2. Validate YAML
uv run python .claude/skills/quarto/scripts/validate_yaml.py document.qmd
3. Edit Content
- Write markdown and code chunks
- Use cell options to control output
- Add cross-references for figures/tables
4. Preview
quarto preview document.qmd
5. Render Final
quarto render document.qmd
quarto render document.qmd --to all # All formats
6. Batch Render
uv run python .claude/skills/quarto/scripts/render_all.py \
--pattern "reports/*.qmd"
Project Configuration
_quarto.yml
project:
type: default
output-dir: _output
format:
html:
theme: cosmo
toc: true
code-fold: true
typst:
toc: true
execute:
echo: true
warning: false
cache: true
Recommended Structure
project/
├── analysis/
│ ├── 01_import.qmd
│ └── 02_analyze.qmd
├── reports/
│ └── summary.qmd
├── _quarto.yml
├── references.bib
└── data/
Troubleshooting
YAML Errors
- Use spaces, not tabs for indentation
- Ensure colons have space after:
key: value
- Quote strings with special characters
- Validate with:
uv run python .claude/skills/quarto/scripts/validate_yaml.py
Code Execution Errors
- Verify kernel is installed (
jupyter, IRkernel)
- Check code chunk syntax (triple backticks + language)
- Use
#| error: true to show errors without failing
- Check file paths are relative and correct
Rendering Failures
- Run
quarto check to verify installation
- Use
quarto render --verbose for details
- Check for missing packages in code chunks
- For Typst: ensure Quarto 1.4+ is installed
Debug Commands
quarto check # Verify installation
quarto render --verbose # Detailed output
quarto render --keep-md # Keep intermediate files
References
Project References
Available Assets
| Template |
Description |
assets/template_html.qmd |
Basic HTML analysis |
assets/template_typst.qmd |
Basic Typst document |
assets/template_dual.qmd |
Both formats |
assets/template_report.qmd |
Formal report |
assets/_quarto.yml |
Project configuration |
Available Scripts
| Script |
Purpose |
scripts/create_quarto.py |
Generate from templates |
scripts/render_all.py |
Batch render |
scripts/validate_yaml.py |
Check YAML syntax |
External Resources
Best Practices
- Use relative paths - Keep documents portable
- Cache long computations -
cache: true for expensive chunks
- Test incrementally - Render frequently during development
- Use project config - Set common options in
_quarto.yml
- Version control .qmd - Commit source, not rendered output
- Document dependencies - List required packages in setup chunk
By