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

---
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

1. Use spaces, not tabs for indentation
2. Ensure colons have space after: key: value
3. Quote strings with special characters
4. Validate with: uv run python .claude/skills/quarto/scripts/validate_yaml.py

Code Execution Errors

1. Verify kernel is installed (jupyter, IRkernel)
2. Check code chunk syntax (triple backticks + language)
3. Use #| error: true to show errors without failing
4. Check file paths are relative and correct

Rendering Failures

1. Run quarto check to verify installation
2. Use quarto render --verbose for details
3. Check for missing packages in code chunks
4. 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

• Quarto Documentation
• HTML Format Guide
• Typst Format Guide
• Code Execution
• Cross-References

Best Practices

1. Use relative paths - Keep documents portable
2. Cache long computations - cache: true for expensive chunks
3. Test incrementally - Render frequently during development
4. Use project config - Set common options in _quarto.yml
5. Version control .qmd - Commit source, not rendered output
6. Document dependencies - List required packages in setup chunk