quarto-prerender

Important

This project is archived. Its rendering behavior is now built into Foliate, which should be used for new work. The existing package remains available only for reproducibility.

Render Quarto .qmd files to Markdown, designed to work as a pre-processor for static site generators.

.qmd → .md + figures

Installation

# Requires Quarto CLI
brew install quarto  # macOS

# Install the tool
uv sync

Python Environment for Notebooks

Quarto needs a Python environment with Jupyter and your notebook dependencies (numpy, matplotlib, etc.). Create a separate data science venv:

# Create the environment
uv venv ~/envs/datascience --python 3.12

# Install packages
uv pip install --python ~/envs/datascience/bin/python \
  jupyter numpy matplotlib pandas

# Use it with quarto-prerender
quarto-prerender pages/ --python ~/envs/datascience/bin/python

Add more packages as needed for your notebooks.

Usage

# Render all .qmd files in a directory
quarto-prerender pages/

# With options
quarto-prerender pages/ \
  --cache .quarto_cache \
  --assets pages/assets/quarto \
  --force

# Watch mode
quarto-prerender pages/ --watch

# Verbose output
quarto-prerender pages/ -v

How It Works

1. Finds all .qmd files in the target directory
2. Runs quarto render with GFM output format
3. Moves generated figures to assets/quarto/{path}/
4. Fixes figure paths in the generated .md
5. Preserves original frontmatter (public, published, etc.)

Directory Structure

pages/
├── analysis/
│   ├── report.qmd          # Source
│   └── report.md           # Generated
└── assets/
    └── quarto/             # Generated figures
        └── analysis/
            └── report_files/
                └── figure-1.png

Obsidian Integration

Use the qmd-as-md-obsidian plugin to edit .qmd files in Obsidian.

Example .qmd File

---
title: "Analysis Report"
public: true
date: 2025-01-15
tags: [ml, analysis]
execute:
  freeze: auto
jupyter: python3
---

# Model Performance

```{python}
#| label: fig-loss
#| fig-cap: "Training loss over epochs"
#| out-width: "600px"

import matplotlib.pyplot as plt
import numpy as np

epochs = np.arange(100)
loss = np.exp(-epochs/20) + 0.1 * np.random.randn(100)

plt.figure(figsize=(10, 6))
plt.plot(epochs, loss)
plt.xlabel("Epoch")
plt.ylabel("Loss")
plt.show()

## Figure Sizing

Figures are responsive by default (no fixed width). To set a specific width for a figure, use Quarto's `out-width` option:

```python
#| out-width: "600px"

For responsive images on mobile, ensure your site's CSS includes img { max-width: 100%; }.

Gitignore

Add to your content repository's .gitignore:

# Quarto cache
.quarto_cache/

# Generated figures
assets/quarto/