md2pdf

name	md2pdf
description	Convert Markdown files to beautifully styled PDFs with full Chinese font support. Use when: (1) Converting .md files to PDF format, (2) Creating printable documents from Markdown, (3) Generating book chapters or story PDFs, (4) Needing PDF output with custom styling (colors, fonts, backgrounds), (5) Working with Chinese text that needs proper rendering in PDF.

Markdown to PDF Converter

Convert Markdown to PDF with Chinese font support and customizable styling.

Quick Start

The script uses uv inline metadata - no manual dependency installation needed:

# Basic conversion (uv auto-installs dependencies)
uv run scripts/md2pdf.py input.md output.pdf

# With custom CSS
uv run scripts/md2pdf.py input.md output.pdf --style assets/vintage-paper.css

# With custom title
uv run scripts/md2pdf.py input.md output.pdf --title "Chapter Title"

# Or make executable and run directly
chmod +x scripts/md2pdf.py
./scripts/md2pdf.py input.md output.pdf

Note: On macOS, the script automatically configures Homebrew library paths.

Available Styles

Two pre-built styles in assets/:

Style	File	Description
Vintage Paper	vintage-paper.css	Warm cream background, brown text, serif fonts. Ideal for stories and literature.
Modern Clean	modern-clean.css	White background, dark text, sans-serif fonts. Ideal for technical documents.

Default Style Features

The built-in default style (vintage paper) includes:

• Background: Warm cream (#FAF6F0)
• Text color: Dark brown (#4A3728)
• Heading color: Darker brown (#3D2B1F)
• Font: Chinese serif (Noto Serif SC, Songti SC)
• Line height: 1.8
• Paragraph indent: 2em (Chinese style)
• Page footer: Page numbers

Customization

To customize styling, copy an existing CSS file and modify:

@page {
    size: A4;                        /* Paper size */
    margin: 2.5cm 2cm;               /* Page margins */
    background-color: #FAF6F0;       /* Page background */
}

body {
    font-family: "Noto Serif SC", serif;  /* Font stack */
    font-size: 12pt;                      /* Base font size */
    line-height: 1.8;                     /* Line spacing */
    color: #4A3728;                       /* Text color */
}

Chinese Font Priority

The converter uses this font fallback chain:

1. Noto Serif SC (Google Noto fonts)
2. Source Han Serif SC (Adobe fonts)
3. Songti SC (macOS)
4. STSong (macOS)
5. SimSun (Windows)

Ensure at least one of these fonts is installed on the system.

Script API

from md2pdf import convert_md_to_pdf

convert_md_to_pdf(
    input_path="chapter.md",
    output_path="chapter.pdf",
    custom_css="assets/vintage-paper.css",  # Optional
    title="Chapter 1"                        # Optional
)

Troubleshooting

WeasyPrint system dependencies

# macOS (library path is auto-configured by script)
brew install pango

# Ubuntu/Debian
sudo apt install libpango-1.0-0 libpangocairo-1.0-0

Missing Chinese fonts

# macOS
brew install font-noto-serif-cjk-sc

# Ubuntu/Debian
sudo apt install fonts-noto-cjk