mk2pdf - Markdown to PDF Converter

mk2pdf converts Markdown files to high-quality PDF documents with full support for Mermaid diagrams, syntax highlighting, and professional formatting.

How It Works

1. Converts Markdown to HTML using mk2html
2. Launches a headless Chromium browser via Playwright
3. Renders the HTML with full JavaScript execution
4. Exports to PDF with print-optimized styles

This approach ensures Mermaid diagrams are fully rendered and syntax highlighting is preserved.

Requirements

pip install mk2html[pdf]

Chromium is automatically installed on first use.

Usage

mk2pdf <input.md> [options]

Options

Page Sizes

Margin Units

Supports various units:
- 1in - inches
- 2cm - centimeters
- 20mm - millimeters
- 72px - pixels

Examples

Basic Conversion

mk2pdf README.md

Creates README.pdf in the same directory.

Custom Output File

mk2pdf docs/guide.md -o output/documentation.pdf

US Letter Size

mk2pdf README.md --page-size letter

Landscape Orientation

mk2pdf README.md --landscape

Custom Margins

mk2pdf README.md --margin 0.5in
mk2pdf README.md --margin 2cm

Smaller Margins for More Content

mk2pdf README.md --margin 0.25in --page-size letter

Dark Theme PDF

mk2pdf README.md --theme dark

Note: Dark theme PDFs use more ink when printed.

Complex Documents with Mermaid

# Increase wait time for complex diagrams
mk2pdf complex-doc.md --wait 5000

Disable Features

# No Mermaid (faster)
mk2pdf README.md --no-mermaid

# No line numbers in code
mk2pdf README.md --no-line-numbers

# Standard Markdown line breaks
mk2pdf README.md --no-breaks

Batch Conversion

# Convert all markdown files in a directory
for f in docs/*.md; do
    mk2pdf "$f" -o "output/$(basename "${f%.md}.pdf")"
done

Automatic Chromium Installation

On first run, if Chromium is not installed, mk2pdf will automatically download it:

$ mk2pdf document.md
Chromium not found. Installing automatically...
(This is a one-time setup, ~150MB download)
✓ Chromium installed successfully!
Converting 'document.md' to PDF...
...

Output Details

The PDF includes:
- All rendered content (no interactive elements)
- Fully rendered Mermaid diagrams as vector graphics
- Syntax-highlighted code blocks with colors preserved
- Tables with proper formatting
- Images (if accessible)

Elements hidden in PDF:
- Header bar
- Sidebar / Table of Contents
- Theme toggle
- Progress bar
- Back to top button

Print Optimization

The PDF is optimized for printing:
- Background colors preserved (print-color-adjust: exact)
- Page breaks avoided in awkward places
- Code blocks stay together
- Headings don't orphan at page bottom

Troubleshooting

Mermaid Diagrams Not Rendering

Increase the wait time:

mk2pdf document.md --wait 5000

Large File Size

• Mermaid diagrams are embedded as SVG (vector)
• Syntax highlighting adds some size
• Use --no-mermaid if not needed

Slow Conversion

• First run downloads Chromium (~150MB)
• Complex Mermaid diagrams take time to render
• Reduce --wait for simple documents

Permission Errors

If Chromium fails to install:

# Manual installation
playwright install chromium

Memory Issues with Large Documents

For very large documents, the browser may need more memory:

# Set Node.js memory limit (if applicable)
export NODE_OPTIONS="--max-old-space-size=4096"
mk2pdf large-document.md

Comparison: mk2html vs mk2pdf