md2pdf — Markdown to PDF in Pure Python

md2pdf converts your Markdown documents into beautiful, print-ready PDFs using pure Python — no Pandoc, Node.js, or headless Chrome needed. Powered by ReportLab and mistletoe.

Why md2pdf?

Most Markdown-to-PDF tools require heavy system dependencies — and even then, getting diagrams or math to render often means installing additional packages. md2pdf works out of the box:

Beyond zero system dependencies, you also get:

• Diagrams & Math — Mermaid and LaTeX via Kroki (with SHA-256 disk caching); matplotlib used for offline LaTeX rendering when configured
• PDF bookmarks — every heading clickable in your PDF viewer's navigation panel
• Multi-page tables — split cleanly across pages with repeated headers
• Colour emoji — Twemoji-powered PNG emoji in your PDFs
• Extensible plugins — custom handlers, themes, and preprocessors

Performance

Although performance was not a primary design goal, md2pdf is highly efficient. By parsing the Markdown AST and mapping it directly to ReportLab flowables, it naturally avoids browser launching, process forking, and intermediate HTML rendering overhead.

Benchmarks (macOS-arm64, Apple Silicon)

To evaluate compilation speeds, we compared md2pdf against Pandoc (using various PDF engines) and Playwright (Chromium) across documents of different sizes:

• Cold Start: Spawns a clean process to capture initialization costs (like browser startup for Playwright or module import overhead for md2pdf).
• Warm Start (Median): Measures rendering throughput by averaging subsequent runs in a warm environment.

Warm Start Rendering Speed (Median)

Cold Start Rendering Speed

Summary Metrics (seconds, lower is better)

Note: For medium.md, md2pdf's cold start is higher because it contains mathematical formulas, which initializes the LaTeX math typesetting subsystem. For large.md (which has no math), md2pdf's cold start is much faster.

To run these benchmarks on your local system:

make benchmark

Installation

Using uv (recommended):

uv tool install pymd2pdf

Using pip:

pip install pymd2pdf

Heavy math documents (physics, engineering)? Install the optional matplotlib backend for faster offline LaTeX rendering:

pip install "pymd2pdf[matplotlib]"

or

uv tool install "pymd2pdf[matplotlib]"

Note: The PyPI package name is pymd2pdf, but the CLI command and Python import are both md2pdf.

Quick Start

# Convert a Markdown file to PDF
md2pdf input.md -o output.pdf

# Run validation checks without producing a PDF
md2pdf input.md --validate-only

# Work offline (diagrams show source code placeholder instead)
md2pdf input.md -o output.pdf --offline

That's it. For most use cases, the first command is all you need.

Key Features

• Standard Elements: Headings (H1–H6), paragraphs, lists, blockquotes, horizontal rules, and hyperlinks.
• Multi-page Tables: Tables split cleanly across page boundaries with repeated column headers on each page.
• Diagrams & Math: Mermaid diagrams and LaTeX math blocks rendered via the Kroki API, with transparent margin cropping, offline fallbacks, and SHA-256 disk caching.
• PDF Bookmarks & Outline Panel: Every heading (H1–H6) becomes a clickable, correctly nested entry in your PDF viewer's navigation/bookmarks panel.
• Colour Emoji: Twemoji-powered PNG emoji rendering in PDFs, with graceful network fallbacks.
• Admonitions & Callouts: GitHub-style alerts (> [!NOTE], > [!WARNING]) and MkDocs/Obsidian fenced containers (:::note).
• Broad Unicode Support: Bundled DejaVu Sans fonts cover Latin Extended, Greek, Cyrillic, math operators, arrows, and box-drawing — no system font dependency needed.
• Custom Fonts & Themes: Supply your own TTF fonts and TOML-based theme overrides.
• Extensible Plugin System: Load custom element handlers, preprocessors, post-processors, and stylesheet/theme layers.
• Typesetting Safeguards: Orphaned heading prevention, ghost page elimination, and widow/orphan protection.
• Pre-render Validation: Catches nested tables, empty diagrams, and unsupported elements before committing to a render.

CLI Options

Python API

from md2pdf import convert, Config, Pipeline

# One-liner conversion
convert("input.md", "output.pdf")

# Advanced: custom config and pipeline
config = Config(
    offline=False,
    cache_dir=".md2pdf_cache",
    output_file="my_document.pdf"
)
pipeline = Pipeline(config)

# Validate before rendering
issues = pipeline.validate("# Hello World")
for issue in issues:
    print(f"[{issue.severity}] {issue.code}: {issue.message}")

# Render
pipeline.run(raw_md="# Document Title\n\nSome body text.")

Configuration

md2pdf auto-discovers a md2pdf.toml config file in these locations (in order):

1. ./md2pdf.toml (project-local)
2. ~/.config/md2pdf/md2pdf.toml
3. ~/.md2pdf.toml

You can also pass one explicitly with --config. See the annotated md2pdf.toml.example for all available options.

Documentation & Examples

Example Templates

Tech Stack

Development Setup

# Clone the repository
git clone https://github.com/Hari31416/md2pdf.git
cd md2pdf

# Create virtual environment and install all dependencies (including dev)
uv sync
source .venv/bin/activate

# Install pre-commit hooks
uv run pre-commit install

# Run the test suite
uv run pytest

To rebuild all documentation PDFs and example renders:

make docs

Architecture Overview

md2pdf runs as a four-stage pipeline: preprocessing → parsing/validation → element rendering → layout composition.

graph TD
    Input[Markdown File] --> Pre[Preprocessors]
    Pre --> Parser[MarkdownParser]
    Parser --> Tokens[Token Stream]
    Tokens --> Val[DocumentValidator]
    Tokens --> Reg[Plugin/Handler Registry]
    Reg --> Handlers[Element Handlers]
    Handlers --> Kroki[Kroki API / Cache]
    Handlers --> Flowables[ReportLab Flowables]
    Flowables --> Layout[LayoutComposer]
    Layout --> Post[Postprocessors]
    Post --> Renderer[ReportLab PDF Engine]
    Renderer --> Output[Output PDF]

For detailed sequence-level logic, see the User Guide.

Project Structure

md2pdf/
├── docs/                   # Documentation suite (Markdown & consolidated PDF)
├── examples/               # Production-grade example templates with rendered PDFs
├── md2pdf/                 # Core source package
│   ├── assets/             # Kroki client, caching, and fallback elements
│   ├── core/               # Engine pipeline, parser, validator, layout, registry
│   ├── handlers/           # Element-specific flowable generators
│   ├── styles/             # Default stylesheet and theme configs
│   └── cli.py              # CLI entry point
├── scripts/                # Helper scripts (e.g. build_docs.py)
├── tests/                  # Automated test suite
├── md2pdf.toml.example     # Annotated configuration reference
└── pyproject.toml          # Build system and dependency declaration