md2pdf-mermaid

md2pdf-mermaid-video-light.mp4

Watch md2pdf-mermaid in action!

Professional Markdown to PDF converter with emoji support and automatic Mermaid diagram rendering

Convert your Markdown documentation to beautiful PDFs with:

✅ Full emoji support 🎉 (colored, native rendering)
✅ Automatic Mermaid diagram rendering (high-quality PNG images)
✅ Table of contents generation (with [TOC] marker)
✅ Page numbering (automatic footer pagination)
✅ Professional formatting (headers, tables, code blocks)
✅ Multiple page sizes (A4, A3, Letter)
✅ Portrait & Landscape orientation support
✅ Full Unicode/UTF-8 support (multilingual text, special characters)
✅ Syntax highlighting for code blocks
✅ CLI and Python API
✅ Fast and reliable

🚀 Quick Start

Installation

# From PyPI (recommended)
pip install md2pdf-mermaid

# Install Playwright browser (required for rendering)
playwright install chromium

Alternative - From Git repository:

pip install git+https://github.com/rbutinar/md2pdf-mermaid.git
playwright install chromium

macOS Users: Use a virtual environment (required for externally-managed Python):

python3 -m venv venv
source venv/bin/activate
pip install md2pdf-mermaid
playwright install chromium

See MACOS_SETUP.md for detailed instructions.

WSL Users: Use Windows Python to avoid dependency issues:

python3.exe -m venv venv  # Windows venv, no sudo needed!
venv/Scripts/pip.exe install md2pdf-mermaid
venv/Scripts/playwright.exe install chromium

See WSL_SETUP.md for details.

Command Line Usage

# Basic conversion (emoji and Mermaid just work!)
md2pdf document.md

# Custom output name
md2pdf document.md -o report.pdf

# Custom title
md2pdf document.md --title "Project Report"

# Page size and orientation
md2pdf document.md --page-size letter --orientation landscape

# High-quality Mermaid diagrams with custom theme
md2pdf document.md --mermaid-scale 3 --mermaid-theme forest

# Use legacy ReportLab engine (faster, no emoji)
md2pdf document.md --engine reportlab

# Disable Mermaid rendering (faster, text-only diagrams)
md2pdf document.md --no-mermaid

# Combine options
md2pdf document.md -o report.pdf --page-size a3 --title "Report"

Python API Usage

from md2pdf import convert_markdown_to_pdf_html

# Read markdown file
with open("document.md", "r") as f:
    markdown_content = f.read()

# Basic conversion (emoji supported!)
result = convert_markdown_to_pdf_html(
    markdown_content,
    "output.pdf",
    title="My Document"
)

# With custom page settings
result = convert_markdown_to_pdf_html(
    markdown_content,
    "report.pdf",
    title="Annual Report",
    page_size="A4",                # Options: 'A4', 'A3', 'Letter'
    orientation="portrait",         # Options: 'portrait', 'landscape'
    enable_mermaid=True            # Enable/disable Mermaid rendering
)

# Legacy ReportLab engine (for advanced PDF features)
from md2pdf import convert_markdown_to_pdf

convert_markdown_to_pdf(
    markdown_content,
    "output.pdf",
    page_numbers=True,
    font_name="arial",
    emoji_strategy="remove"  # ReportLab doesn't support emoji
)

📋 Features

🎨 Two Rendering Engines

HTML Engine (Default) - Recommended ⭐

Full emoji support 🎉 - Colored emoji render natively
Modern CSS styling - Browser-quality rendering
Table of contents - Add [TOC] anywhere in your markdown
Page numbers - Automatic footer pagination (X / Y format)
Best quality - Superior rendering for modern documents

ReportLab Engine (Legacy) - For Special Cases

Custom fonts - TTF font support
Advanced PDF features - Custom headers/footers, bookmarks
Smaller file size - Slightly more compact
No emoji - Emoji are removed for compatibility

# Use HTML engine (default)
md2pdf document.md

# Use ReportLab engine
md2pdf document.md --engine reportlab --emoji-strategy remove

📝 Markdown Support

Headers (H1-H4) with colored borders
Bold, italic, inline code (including in lists!)
Emoji 🎉 ✅ ❌ 🔴 🟢 (full color support with HTML engine)
Bullet lists and numbered lists with full formatting support
Table of contents - Just add [TOC] in your markdown!
Tables with colored headers
Code blocks with syntax highlighting
Horizontal rules
Mermaid diagrams (rendered as high-quality images)
Full Unicode/UTF-8 support (multilingual text, special characters)

📊 Mermaid Diagrams

Automatically renders Mermaid diagrams as high-quality PNG images:

```mermaid
graph LR
    A[Start] --> B[Process]
    B --> C[End]
    style A fill:#90EE90
    style C fill:#FFD700
```

Becomes a visual diagram in the PDF!

Mermaid Features:

Customizable themes: default, neutral, dark, forest, base
Quality control: Scale factor 1-4 for resolution (default: 2 = high quality)
Automatic sizing: Diagrams fit properly on pages
Full-width diagrams: Optimized for readability

📄 PDF Styling

Multiple page sizes: A4, A3, Letter
Portrait and Landscape orientation support
Automatic page numbering in footer (HTML engine)
Table of contents support (HTML engine)
Professional color scheme
Tables with alternating row colors
Code blocks with light gray background
Headers with colored borders
2cm margins on all sides
Full emoji rendering (HTML engine)

🔧 Requirements

Python 3.8+
Chromium browser (via Playwright, ~250 MB)
playwright, reportlab, markdown, pillow (installed automatically)

📚 Use Cases

1. Technical Documentation with Emoji

Convert your modern documentation to PDF:

# API Documentation 🚀

## Quick Start ✅

Install the package and get started! 🎉

### Features
- ✅ Easy to use
- ⚡ Fast performance
- 🔒 Secure by default

2. Architecture Diagrams

Create professional reports with:

Data flow diagrams
System architecture
Process flowcharts
Executive summaries

3. CI/CD Integration

Automatically generate PDFs in your pipeline:

# GitHub Actions example
- name: Generate PDF Documentation
  run: |
    pip install md2pdf-mermaid
    playwright install chromium
    md2pdf README.md -o docs/README.pdf

💡 Advanced Usage

Batch Conversion

from md2pdf import convert_markdown_to_pdf_html
from pathlib import Path

# Convert all markdown files
for md_file in Path("docs").glob("*.md"):
    pdf_file = md_file.with_suffix(".pdf")

    with open(md_file, "r") as f:
        content = f.read()

    convert_markdown_to_pdf_html(content, str(pdf_file), title=md_file.stem)
    print(f"✓ Created {pdf_file}")

Engine Selection

# HTML engine (default) - emoji support
from md2pdf import convert_markdown_to_pdf_html

result = convert_markdown_to_pdf_html(
    markdown_text,
    "output.pdf",
    enable_mermaid=True
)
# result['emoji_support'] == True

# ReportLab engine - advanced PDF features
from md2pdf import convert_markdown_to_pdf

convert_markdown_to_pdf(
    markdown_text,
    "output.pdf",
    page_numbers=True,
    font_name="arial",
    emoji_strategy="remove"
)

🐛 Troubleshooting

"Playwright not found" Error

# Install Playwright
pip install playwright

# Install Chromium browser
playwright install chromium

"Permission denied" When Overwriting PDF

The PDF file is open in a viewer. Close it first, then try again.

Mermaid Diagrams Not Rendering

Check Playwright is installed: python -c "import playwright"
Check Chromium is installed: playwright install --force chromium
Try disabling and re-enabling Mermaid: md2pdf file.md --no-mermaid

Emoji Not Rendering

If you're using the ReportLab engine, emoji are not supported. Switch to HTML engine:

md2pdf document.md --engine html  # or just: md2pdf document.md (HTML is default)

macOS: "externally-managed-environment" Error

macOS uses externally-managed Python. Always use a virtual environment:

# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate

# Install package
pip install md2pdf-mermaid
playwright install chromium

# Use the package (with venv activated)
md2pdf document.md

Note: Remember to activate the virtual environment (source venv/bin/activate) before using md2pdf.

WSL: "Host system is missing dependencies to run browsers"

Best solution: Use Windows Python instead of Linux Python (no sudo needed):

# Create Windows venv from WSL
python3.exe -m venv venv
venv/Scripts/pip.exe install md2pdf-mermaid
venv/Scripts/playwright.exe install chromium
venv/Scripts/md2pdf.exe document.md  # Works perfectly!

See WSL_SETUP.md for complete instructions.

🤝 Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

📝 License

MIT License - see LICENSE file for details

🔗 Related Projects

mermaid - Diagram syntax
reportlab - PDF generation
playwright - Browser automation
python-markdown - Markdown processing

📧 Support

Issues: https://github.com/rbutinar/md2pdf-mermaid/issues
Documentation: https://github.com/rbutinar/md2pdf-mermaid

🎯 Roadmap

Version: 1.4.3 Published: 2025-12-14 PyPI: https://pypi.org/project/md2pdf-mermaid/ Status: Stable Release 🎉

🆕 What's New

v1.4.2 (2025-10-31) - macOS Support & Dependency Fix

Bug Fixes:

🐛 Fixed missing dependency - Added markdown>=3.0.0 to all dependency configurations
- Resolves ModuleNotFoundError: No module named 'markdown' on fresh installations
- Now automatically installed with the package

Documentation:

📖 macOS Setup Guide - Comprehensive MACOS_SETUP.md documentation
- Virtual environment setup instructions for macOS users
- Troubleshooting for "externally-managed-environment" error
- Tips for aliases and global installation
- Tested on macOS 11-15 (Big Sur through Sequoia)
- Apple Silicon (M1/M2/M3/M4) and Intel support confirmed

Improvements:

✅ Better installation experience on macOS
✅ Updated README with macOS-specific instructions
✅ All features fully tested on macOS environment

v1.4.1 (2025-10-30)

🐛 Fixed Mermaid diagram rendering timing issues
⚡ Performance improvement: ~18% faster rendering

v1.4.0 (2025-10-23) - Emoji Support! 🎉

Major New Features:

🎉 Full emoji support - Colored emoji render natively via HTML/Chromium engine
📑 Table of contents - Add [TOC] anywhere in your markdown for automatic TOC
📄 Page numbering - Automatic footer pagination (X / Y format)
🎨 HTML rendering engine - Superior quality, modern CSS styling (now default)
⚡ Dual engine architecture - HTML (default) or ReportLab (legacy) engines

Technical Improvements:

✅ Mermaid diagrams automatically sized to fit pages
✅ Better diagram quality with controlled height limits
✅ Professional page layout with proper margins
✅ Modern CSS styling for all elements
✅ Browser-grade rendering quality

How to Use:

# Emoji now work by default!
md2pdf document.md

# Table of contents
echo "[TOC]" > doc.md
md2pdf doc.md

# Legacy engine (if needed)
md2pdf document.md --engine reportlab

Breaking Changes:

None! Default engine changed to HTML, but ReportLab still available with --engine reportlab

v1.3.1 (2025-10-21)

🐛 Fixed emoji removal for technical symbols (→, ←, ✓, etc.)
🔧 Improved emoji detection accuracy

v1.3.0 (2025-10-21)

✨ Mermaid theme support - 5 color themes available
✨ Mermaid quality control - Scale factor 1-4 for resolution
✨ Automatic emoji removal (for PDF compatibility with ReportLab)
🐛 Fixed Mermaid diagram sizing issues
🐛 Fixed hyperlink rendering

v1.2.0 (2025-10-20)

✨ Full Unicode/UTF-8 support
✨ Customizable fonts (Arial, DejaVu, Helvetica, custom TTF)
✨ Bold & inline code in lists
🐛 Fixed encoding issues

Name		Name	Last commit message	Last commit date
Latest commit History 28 Commits
.github/workflows		.github/workflows
assets		assets
examples		examples
md2pdf		md2pdf
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
GETTING_STARTED.md		GETTING_STARTED.md
LICENSE		LICENSE
MACOS_SETUP.md		MACOS_SETUP.md
README.md		README.md
ROADMAP.md		ROADMAP.md
WSL_SETUP.md		WSL_SETUP.md
pyproject.toml		pyproject.toml
setup.cfg		setup.cfg
setup.py		setup.py

License

rbutinar/md2pdf-mermaid

Folders and files

Latest commit

History

Repository files navigation