quarto-prerender

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/