md2pdf

将Markdown文件转换为具有完整中文字体支持的精美样式PDF。使用场景:(1) 将.md文件转换为PDF格式, (2) 从Markdown创建可打印文档, (3) 生成书籍章节或故事PDF, (4) 需要具有自定义样式(颜色、字体、背景)的PDF输出, (5) 处理需要在PDF中正确渲染的中文文本。

📖 中文导读:将Markdown文件转换为具有完整中文字体支持的精美样式PDF。使用场景:(1) 将.md文件转换为PDF格式, (2) 从Markdown创建可打印文档, (3) 生成书籍章节或故事PDF, (4) 需要具有自定义样式(颜色、字体、背景)的PDF输出, (5) 处理需要在PDF中正确渲染的中文文本。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

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