Skip to content

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

  • Quarto installed (>= 1.5)
  • For PDF output: Quarto will automatically install Typst on first use

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:

![Description](figures/my-chart.png)

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

Further Reading