Metadata-Version: 2.4
Name: quarto-prerender
Version: 0.1.0
Summary: Render Quarto .qmd files to Markdown with figure management
Project-URL: Repository, https://github.com/yy/quarto-prerender
Author-email: YY Ahn <yongyeol@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: jupyter,markdown,quarto,static-site-generator
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Text Processing :: Markup
Requires-Python: >=3.10
Requires-Dist: python-frontmatter>=1.0.0
Requires-Dist: watchdog>=3.0.0
Description-Content-Type: text/markdown

# quarto-prerender

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

```
.qmd → .md + figures
```

## Installation

```bash
# 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:

```bash
# 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

```bash
# 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](https://github.com/danieltomasz/qmd-as-md-obsidian) plugin to edit `.qmd` files in Obsidian.

## Example .qmd File

```yaml
---
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`:

```gitignore
# Quarto cache
.quarto_cache/

# Generated figures
assets/quarto/
```
