md2pdf — Markdown to Professional PDF

Convert Markdown content into beautifully formatted PDF documents using md2pdf (WeasyPrint engine) with a bundled professional CSS stylesheet.

Prerequisites

Before first use, install the required dependencies:

# macOS system dependencies for WeasyPrint
brew install cairo pango gdk-pixbuf libffi

# Python package
pip install md2pdf

On Ubuntu/Debian:

sudo apt install libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf2.0-0 libffi-dev shared-mime-info
pip install md2pdf

Verify installation:

python -c "from md2pdf.core import md2pdf; print('md2pdf ready')"

Quick Start

The simplest way — use the bundled conversion script:

python @scripts/convert.py input.md output.pdf

The script automatically uses the bundled CSS stylesheet at @assets/markdown.css for professional formatting. If no output path is given, it defaults to the input filename with .pdf extension.

Using the Python API Directly

For more control, call md2pdf directly in Python:

from pathlib import Path
from md2pdf.core import md2pdf

# From a Markdown file
md2pdf(
    pdf=Path("output.pdf"),
    md=Path("input.md"),
    css=Path("@assets/markdown.css"),
    base_url=Path("."),  # resolves relative image paths
)

# From a Markdown string
md2pdf(
    pdf=Path("output.pdf"),
    raw="# Hello\n\nThis is **bold** text.",
    css=Path("@assets/markdown.css"),
)

Bundled Stylesheet Features

The @assets/markdown.css provides:

• Page layout: A4 size, 25mm/20mm margins, centered page numbers in footer
• Typography: Serif body text (Noto Serif SC / Libre Baskerville / Georgia), sans-serif headings (Noto Sans SC / Helvetica Neue), optimized line-height 1.7
• Chinese font support: Noto Serif SC, Source Han Serif SC, Songti SC for body; Noto Sans SC, Source Han Sans SC, PingFang SC for headings
• Code: Monospace stack (SF Mono / Cascadia Code / Fira Code), light background, Pygments GitHub-style syntax highlighting
• Tables: Clean borders, alternating row colors, header styling, repeat headers across pages
• Blockquotes: Left blue border, subtle background
• Links: Print-friendly — external URLs shown inline after link text
• Page breaks: Headings never orphaned, tables and code blocks avoid breaking across pages
• First page: Extra top margin, no page number

Customizing the Output

Custom CSS

Pass your own CSS file to override or extend the default styles:

python @scripts/convert.py input.md output.pdf --css my-styles.css

Or via Python API:

md2pdf(pdf=Path("output.pdf"), md=Path("input.md"), css=Path("my-styles.css"))

Common CSS Customizations

Change page size to Letter:

@page { size: letter; }

Add a header with document title:

@page {
    @top-center {
        content: "My Document";
        font-size: 8pt;
        color: #999;
    }
}

Add "Page X of Y" footer:

@page {
    @bottom-center {
        content: counter(page) " / " counter(pages);
        font-size: 9pt;
        color: #888;
    }
}

Change body font:

body { font-family: "Merriweather", Georgia, serif; }

Disable URL display in print:

a[href^="http"]:after { content: none; }

Document Title

Use --title to inject a title heading when the Markdown content doesn't start with one:

python @scripts/convert.py report.md --title "Q4 Engineering Report"

Working with Images

Images with relative paths require base_url to resolve correctly. The conversion script sets this automatically to the Markdown file's parent directory. When using the Python API directly:

md2pdf(
    pdf=Path("output.pdf"),
    md=Path("docs/report.md"),
    css=Path("@assets/markdown.css"),
    base_url=Path("docs/"),  # images in docs/ will resolve correctly
)

Markdown Extensions Supported

The conversion script enables these extensions by default:

• tables — GFM table syntax
• pymdownx.superfences — Nested code blocks with syntax highlighting
• pymdownx.betterem — Improved emphasis handling
• pymdownx.magiclink — Auto-link URLs and issue references
• footnotes — [^1] style footnotes
• smarty — Smart quotes, dashes, ellipses

Troubleshooting

File Reference