Markdown to PDF Converter#

Convert Markdown files to PDF with professional formatting. Supports multiple backends for different use cases.

Backends#

Primary: WeasyPrint (Pure Python)#

• Pros: No system dependencies, pip install only, good CSS support
• Cons: Slightly slower on large documents
• Use for: Most use cases, especially when you can't install system packages

Optional: Pandoc + wkhtmltopdf#

• Pros: Most powerful, LaTeX support, best typography
• Cons: Requires system package installation
• Use for: Academic papers, complex documents, LaTeX math

Quick Start#

bash

# Using WeasyPrint (recommended, auto-installed)
python3 scripts/md_to_pdf.py input.md output.pdf

# Using Pandoc (if installed)
python3 scripts/md_to_pdf.py input.md output.pdf --backend pandoc

Usage from Agent#

Basic Conversion#

python

# Convert markdown to PDF
exec("python3 skills/md-to-pdf-advanced/scripts/md_to_pdf.py /path/to/input.md /path/to/output.pdf")

With Custom CSS#

python

# Apply custom theme
exec("python3 skills/md-to-pdf-advanced/scripts/md_to_pdf.py input.md output.pdf --css skills/md-to-pdf-advanced/assets/github-theme.css")

With Options#

python

# Landscape, custom margins
exec("python3 skills/md-to-pdf-advanced/scripts/md_to_pdf.py input.md output.pdf --orientation landscape --margin 15mm")

Features#

• ✅ Syntax-highlighted code blocks
• ✅ Tables with styling
• ✅ Images (local and remote)
• ✅ Headers and footers with page numbers
• ✅ Custom CSS themes
• ✅ Page size and orientation options
• ✅ Adjustable margins

CSS Themes#

Available in assets/:

• github-theme.css - GitHub-like styling
• minimal-theme.css - Clean minimal look
• academic-theme.css - Academic paper style

Troubleshooting#

WeasyPrint fails to install#

bash

# Install system dependencies first (Ubuntu/Debian)
sudo apt-get install python3-dev libffi-dev libxml2-dev libxslt1-dev

# Then install Python packages
pip3 install weasyprint markdown Pygments

Images not showing#

Use absolute paths or ensure images are relative to the markdown file location.

Fonts look wrong#

WeasyPrint uses system fonts. Install the fonts you reference in CSS:

bash

# Ubuntu/Debian
sudo apt-get install fonts-liberation fonts-dejavu

# macOS
brew install --cask font-liberation

Emoji display as □ (boxes) or not rendered#

PDF 中 emoji（如 ✅、🔄、📋）显示为方框是因为系统缺少彩色 Emoji 字体支持。

解决方案：

bash

# 1. 安装 Google Noto Color Emoji 字体（支持全量 Unicode Emoji）
# Fedora/RHEL/CentOS
dnf install -y google-noto-emoji-color-fonts

# Ubuntu/Debian
sudo apt-get install fonts-noto-color-emoji

# 2. 刷新字体缓存让系统识别新字体
fc-cache -fv

# 3. 重新转换 PDF
python3 skills/md-to-pdf-advanced/scripts/md_to_pdf.py input.md output.pdf

替代方案（如果不想安装字体）：

将 Markdown 中的 emoji 替换为文字描述或 ASCII 符号：

Emoji文字替代ASCII 替代✅[OK] 或 (完成)``[x]❌[FAIL] 或 (失败)``[ ]🔄[更新] 或 (刷新)``~>📋[列表] 或 (任务)``[#]⚠️[警告] 或 (注意)``!💡[提示] 或 (建议)``i🔧[修复] 或 (工具)`🐛[BUG] 或 (缺陷)``*