omk-pdf-gen

PDF Generation Skill

Trigger Examples

• "帮我生成一个报价 PDF"
• "把这个内容导出成 PDF"
• "PDF 中文乱码怎么办"
• "generate a comparison PDF for this customer"
• "create a budget proposal PDF"

Approach: HTML + weasyprint

Use HTML + CSS → weasyprint pipeline. Do NOT use reportlab for documents containing CJK text.

Why:

• reportlab CID fonts (STSong-Light) have incomplete glyph coverage — symbols like • render as garbage (e.g. "煉")
• reportlab cannot read macOS SIP-protected TTC fonts (PingFang etc.)
• reportlab canvas API requires manual coordinate positioning — fragile and ugly
• weasyprint uses system fontconfig — correct font resolution out of the box

Workflow

Step 1: Write HTML string in Python

HTML = """\
<!DOCTYPE html>
<html lang="zh">
<head><meta charset="utf-8">
<style>
@page { size: A4; margin: 2cm 2.2cm; }
body { font-family: "Hiragino Sans GB", "Heiti SC", "Noto Sans CJK SC", sans-serif; ... }
</style></head>
<body>...</body></html>
"""

Step 2: Write to temp HTML, convert, clean up

import subprocess, os
html_tmp = output_path.replace('.pdf', '.html')
with open(html_tmp, 'w', encoding='utf-8') as f:
    f.write(HTML)
subprocess.run(['weasyprint', html_tmp, output_path], check=True)
os.remove(html_tmp)

Font Rules (Critical)

Platform	CSS font-family	Notes
macOS	"Hiragino Sans GB", "Heiti SC"	Verified via fc-list :lang=zh
Linux	"Noto Sans CJK SC", "WenQuanYi Micro Hei"	Install fonts-noto-cjk if missing
Fallback	sans-serif	Always include as last resort

Never use these in weasyprint CSS:

• -apple-system — weasyprint doesn't understand Apple system font aliases
• "PingFang SC" — fontconfig often can't resolve it even though macOS has it
• "STSong-Light" — CID font name, not a real font family for CSS

Before generating, verify CJK fonts are available:

fc-list :lang=zh family | head -10

Styling Best Practices