When should I use md2pdf?

md2pdf is useful in the following scenarios: • Technical Documentation: Convert project READMEs or technical guides into clean, professional PDFs using the 'Modern Clean' style for distribution. • Creative Publishing: Transform stories, poems, or book chapters into aesthetically pleasing PDFs with the 'Vintage Paper' theme for a classic literary look. • Multilingual Document Generation: Ensure perfect rendering of Chinese characters (Noto Serif SC/Songti) in PDF exports, solving common font display issues in standard converters. • Custom Branded Reports: Apply custom CSS to match corporate branding (colors, fonts, margins) when generating reports from Markdown-based data. • Automated Workflow Integration: Use the Python API or CLI to automate the generation of styled PDF documents within a CI/CD pipeline or local script.

md2pdf

from aicoder2048

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.

⭐0stars🔀0forks📁View on GitHub🕐Updated Dec 23, 2025

When & Why to Use This Skill

This Claude skill provides a powerful utility for converting Markdown files into professionally formatted PDF documents. It distinguishes itself with full support for Chinese typography and customizable CSS styling, enabling users to transform plain text into high-quality, printable assets like ebooks, technical manuals, and reports with ease.

Use Cases

Technical Documentation: Convert project READMEs or technical guides into clean, professional PDFs using the 'Modern Clean' style for distribution.
Creative Publishing: Transform stories, poems, or book chapters into aesthetically pleasing PDFs with the 'Vintage Paper' theme for a classic literary look.
Multilingual Document Generation: Ensure perfect rendering of Chinese characters (Noto Serif SC/Songti) in PDF exports, solving common font display issues in standard converters.
Custom Branded Reports: Apply custom CSS to match corporate branding (colors, fonts, margins) when generating reports from Markdown-based data.
Automated Workflow Integration: Use the Python API or CLI to automate the generation of styled PDF documents within a CI/CD pipeline or local script.

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."

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:

Noto Serif SC (Google Noto fonts)
Source Han Serif SC (Adobe fonts)
Songti SC (macOS)
STSong (macOS)
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