Reporting with Quarto¶
This tutorial covers how to use the reporting framework included in the project template. Reports live in the reports/ directory and use Quarto to render notebooks and markdown files into polished output formats.
Prerequisites¶
Project Structure¶
reports/
├── _quarto.yml # Project-level Quarto config
├── _combined_template.qmd # Template report (Quarto markdown)
├── _combined_template.ipynb # Template report (Jupyter notebook)
└── figures/ # Shared figures and images
The _quarto.yml file configures all reports in the directory:
project:
title: "reports"
output-dir: _output
All rendered output goes to reports/_output/, which is gitignored via reports/.gitignore.
Getting Started¶
1. Choose Your Format¶
Reports can be authored as either Quarto markdown (.qmd) or Jupyter notebooks (.ipynb). Both support the same YAML front matter and rendering options. Use whichever fits your workflow:
.qmd— plain text, version-control friendly, good for narrative-heavy reports.ipynb— interactive, good for exploratory analysis that becomes a deliverable
2. Create a New Report¶
Copy the template and rename it:
# From a Quarto markdown template
cp reports/_combined_template.qmd reports/my-analysis.qmd
# Or from a notebook template
cp reports/_combined_template.ipynb reports/my-analysis.ipynb
3. Configure the Front Matter¶
Edit the YAML front matter at the top of your report:
---
title: "My Analysis"
subtitle: "Q1 2025 Results"
abstract: "Summary of findings from Q1 data analysis."
date: 2025-04-01
author:
- name: Jane Smith
email: jsmith@example.com
affiliation:
- name: Your Organization
city: Anytown
state: USA
url: www.example.com
format:
typst: default
---
4. Choose an Output Format¶
Uncomment the format(s) you want in the format: block. The template includes several options:
| Format | Use Case |
|---|---|
typst: default |
PDF output via Typst (fast, modern) |
html |
Self-contained HTML pages |
revealjs |
Browser-based slide decks |
You can enable multiple formats simultaneously — Quarto will render all of them.
Rendering Reports¶
The template includes a just command for rendering all reports:
just render
This runs quarto render reports/ and writes output to reports/_output/.
For more control, you can call Quarto directly:
# Render a single report
quarto render reports/my-analysis.qmd
# Render to a specific format
quarto render reports/my-analysis.qmd --to typst
# Preview with live reload
quarto preview reports/my-analysis.qmd
Working with Figures¶
Place shared images in reports/figures/ and reference them in your report:

For programmatic figures, generate them inline with Python code cells — Quarto will embed them automatically.
Tips¶
- Multiple formats: You can render the same report to PDF, HTML, and slides by listing multiple formats in the front matter. This is useful for creating both a detailed report and a presentation from the same source.
- Quarto extensions: If you need custom styling, Quarto supports extensions that can add new formats or modify existing ones.
- Cross-references: Use Quarto's cross-reference syntax to reference figures, tables, and sections within your report.
- Parameters: Use Quarto parameters to make reports configurable (e.g., date ranges, data sources).