Quarto Document Generation Skill
Contents
- •When to Use This Skill
- •Quick Start
- •Output Formats
- •Code Chunks
- •Document Workflow
- •Project Configuration
- •Troubleshooting
- •References
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
markdown
---
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
bash
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
yaml
format:
html:
toc: true
toc-depth: 3
code-fold: true
code-tools: true
embed-resources: true
theme: cosmo
Typst Configuration
yaml
format:
typst:
toc: true
number-sections: true
papersize: us-letter
margin:
x: 1.25in
y: 1.25in
fontsize: 11pt
Multiple Formats
yaml
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
markdown
```{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
markdown
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
bash
# 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
bash
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
bash
quarto preview document.qmd
5. Render Final
bash
quarto render document.qmd quarto render document.qmd --to all # All formats
6. Batch Render
bash
uv run python .claude/skills/quarto/scripts/render_all.py \ --pattern "reports/*.qmd"
Project Configuration
_quarto.yml
yaml
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
code
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: trueto show errors without failing - •Check file paths are relative and correct
Rendering Failures
- •Run
quarto checkto verify installation - •Use
quarto render --verbosefor details - •Check for missing packages in code chunks
- •For Typst: ensure Quarto 1.4+ is installed
Debug Commands
bash
quarto check # Verify installation quarto render --verbose # Detailed output quarto render --keep-md # Keep intermediate files
References
Project References
- •Quick Reference - Comprehensive syntax reference
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: truefor 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