md2pdf

Markdown to PDF converter with Mermaid diagram support. Generates styled, print-ready A4 PDFs from .md files using Pandoc and wkhtmltopdf.

Mermaid code blocks are automatically rendered to PNG and embedded in the final PDF — no manual export needed.

Features

• Mermaid diagrams — ```mermaid blocks are rendered to PNG and inlined automatically
• Styled output — bundled CSS for clean A4 typography, tables, and code blocks
• Page footer — page numbers and optional branding
• Zero Python deps — pure Python, no pip dependencies beyond the standard library
• Auto-install — on Windows, Pandoc and wkhtmltopdf are installed via winget if missing

Installation

pip install -e .

This registers the md2pdf CLI command.

Usage

# Convert a markdown file to PDF
md2pdf report.md

# Specify a custom output directory
md2pdf report.md -o build/

Output structure

pdf/report/
  report.pdf
  images/              # created only if the markdown has mermaid blocks
    diagram_1.png
    diagram_2.png

By default, output goes to <markdown_dir>/pdf/<name>/.

Example

Given a markdown file with a Mermaid block:

# System Architecture

```mermaid
flowchart LR
    A[Client] --> B[API Gateway]
    B --> C[Service A]
    B --> D[Service B]
    C --> E[(Database)]
```

The gateway routes requests to the appropriate service.

Running md2pdf architecture.md produces a styled PDF with the diagram rendered as an image.

Requirements

Tool	Install	Purpose
Pandoc	winget install pandoc	Markdown to HTML conversion
wkhtmltopdf	winget install wkhtmltopdf.wkhtmltox	HTML to PDF rendering
Mermaid CLI	npm install -g @mermaid-js/mermaid-cli	Diagram rendering (optional)

On Windows, Pandoc and wkhtmltopdf are automatically installed via winget if not found in PATH.

Project structure

md2pdf/
  cli.py        # CLI entry point and argument parsing
  convert.py    # Core conversion: Mermaid rendering, Pandoc invocation
  styles.css    # Bundled A4 stylesheet
  footer.html   # Page footer template
  assets/       # Static assets (logo, etc.)

Configuration

• Custom Mermaid path — set the MMDC_PATH environment variable to point to your mmdc executable
• Custom output dir — use the -o flag to override the default output location

License

MIT