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
- 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: 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
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
tomevault-io