any2pdf 是一个将 Markdown 文件转换为出版级 PDF 的技能，使用 Python 的 reportlab 库作为主引擎，并在需要时回退到 pandoc + XeLaTeX。它经过大量真实中文技术报告的迭代开发，解决了朴素 MD→PDF 转换器容易出错的若干难题。
用途
当用户需要将 .md 文件转换为 .pdf、希望获得专业排版效果、文档包含 CJK（中日韩）字符与拉丁文字混排、包含围栏代码块、Markdown 表格或嵌套列表、包含本地/远程图片、Obsidian callout、emoji 或数学公式，或希望在 PDF 中加入封面页、目录或水印时，可使用本技能。
主要能力
- 封面页、扉页（封面后的全页插图）、封底物料（名片/二维码/品牌图片或纯文字信息）
- 目录、页眉页脚、书签（PDF 侧边栏书签与命名锚点）
- 水印（自定义文字、字号、透明度、角度、间距）
- 多种设计主题：暖学术、经典论文、Tufte、期刊蓝、精装书、中国红、水墨、GitHub、Nord 冰霜、海洋、LaTeX 清爽、咨询深蓝
- 字体系统：macOS 上使用 Palatino（拉丁正文）、Songti SC（CJK 正文）、Menlo（代码），Linux 上自动回退
- CJK 包装：_font_wrap() 将 CJK 字符段包裹在 <font> 标签中实现自动字体切换
- 混排文本渲染：_draw_mixed() 在画布上处理 CJK/拉丁混排文本（封面、页眉、页脚）
- 代码块处理：esc_code() 保留缩进、行内对齐与换行
- 智能表格宽度：按内容长度比例分配列宽，最小 18mm
- 标题预处理器：_preprocess_md() 拆分合并标题（如 # Part## Chapter）
- 图片处理：本地、相对、file:// 与远程 Markdown 图片按比例缩放至正文框，出错时显示回退文本
- Callout 渲染：Obsidian 风格 > [!NOTE] 块渲染为主题化方框 callout
- 公式渲染：显示公式使用可选的 matplotlib mathtext 图片，带样式化文本回退
- Emoji 回退：emoji 渲染为缓存的 Twemoji PNG，或使用本地 emoji 字体回退
使用方式
快速开始命令：
python md2pdf/scripts/md2pdf.py
--input report.md
--output report.pdf
--title "My Report"
--author "Author Name"
--theme warm-academic
除 --input 外所有参数均可选，会应用合理默认值。
转换前必须使用 AskUserQuestion 工具询问设计风格、扉页图片、水印、封底物料等选项，以交互式提示方式呈现，而非纯文本列表。用户选择映射到 CLI 参数，例如设计风格 a-k 对应 --theme，扉页本地图片对应 --frontispiece <path>，水印文字对应 --watermark "文字"，封底图片对应 --banner <path>，封底文字对应 --disclaimer 与 --copyright。
主题名称映射：a) 暖学术→warm-academic；b) 经典论文→classic-thesis；c) Tufte→tufte；d) 期刊蓝→ieee-journal；e) 精装书→elegant-book；f) 中国红→chinese-red；g) 水墨→ink-wash；h) GitHub→github-light；i) Nord→nord-frost；j) 海洋→ocean-breeze；k) LaTeX 清爽→latex-clean（pandoc+XeLaTeX 原生排版，无封面）；l) 咨询深蓝→consulting-navy。
若用户选择 AI 生成扉页：读取文档标题与前几段，使用图像生成工具创建与所选设计风格匹配的主题插图，展示供确认后通过 --frontispiece /path/to/image.png 传入。
架构流程：Markdown → 预处理（拆分合并标题）→ 解析（感知代码围栏）→ Story（reportlab flowables）→ PDF 构建。
配置参考：多数选项也可在文件顶部 YAML 风格 frontmatter 中设置，显式 CLI 参数优先于 frontmatter 值。主要参数包括 --input（必填）、--output（默认 output.pdf）、--title、--subtitle、--author、--date、--version、--watermark、--theme（默认 warm-academic）、--theme-file、--cover（默认 true）、--toc（默认 true）、--page-size（默认 A4）、--frontispiece、--banner、--header-title、--footer-left、--stats-line、--stats-line2、--edition-line、--disclaimer、--copyright、--code-max-lines（默认 30）、--image-cover（默认 false）、--heading-top-spacer（默认 5mm）、--wm-size、--wm-opacity（默认 0.1）、--wm-angle（默认 35）、--wm-spacing-x、--wm-spacing-y。
可用主题：warm-academic、nord-frost、github-light、solarized-light、paper-classic、ocean-breeze、consulting-navy。每个主题定义页面背景、墨色、强调色、淡化文字、边框、代码背景、水印色调。
回退引擎：pandoc + XeLaTeX
当 reportlab 失败时（例如宽/复杂表格导致表格宽度计算无限循环），回退到 pandoc + XeLaTeX，可生成高质量 CJK PDF 并正确处理表格。
使用 pandoc 引擎的场景：用户选择 latex-clean 主题（k）时 pandoc 为主引擎而非回退；文档包含大量宽多列表格（reportlab 表格布局可能挂起）；文档需要 LaTeX 级排版（两端对齐、断字）；reportlab md2pdf.py 在输入上挂起或崩溃。
基本命令：
pandoc input.md -o output.pdf
--pdf-engine=xelatex
-V CJKmainfont="Songti SC" -V mainfont="Palatino" -V monofont="Menlo"
-V geometry:margin=2.5cm -V fontsize=11pt
--toc -V toc-title="目录" -V documentclass=article
添加水印与页眉页脚时，通过 -V header-includes 追加 fancyhdr 与 draftwatermark 相关 LaTeX 代码。
Pandoc 主题预设定义完整的 pandoc -V 标志集，各主题指定 linkcolor、toccolor、urlcolor 与水印颜色，例如 chinese-red 使用 red/red/red 与 [gray]{0.9}，warm-academic 使用 brown/brown/brown 与 [gray]{0.9}，classic-thesis 使用 brown 与 [gray]{0.85}，ieee-journal 使用 blue 与 [gray]{0.9}，github-light 使用 blue 与 [gray]{0.92}，ink-wash 使用 black 与 [gray]{0.92}，nord-frost 使用 teal 与 [gray]{0.9}，consulting-navy 使用 blue 与 [gray]{0.88}。
latex-clean 完整示例（最简洁的 LaTeX 学术风格）：选择 latex-clean 时跳过 reportlab，直接使用 pandoc 生成，特点为无封面、无扉页、无装饰色块，纯 LaTeX 排版加点线 TOC 引导符，适合内容为王的学术/技术文档。
适用场景
中文技术报告、学术论文、白皮书、政企报告、长篇专著、技术书、数据叙事、正式发表风格文档等需要专业排版的 Markdown 文档转换。
限制
- 输入仅支持 Markdown 文件。若为 HTML、DOCX 或其他格式，需先转换为 Markdown（如 pandoc --wrap=none）。Markdown 中嵌入的 HTML 块会作为文本传递，需在调用 md2pdf 前将可视化内容（图表、复杂表格）预处理为纯 Markdown 表格或图片引用。
- pandoc 回退引擎的限制：无封面页（pandoc article 类无内置封面，如需可用 --include-before-body 加 LaTeX 片段）；不支持扉页/封底（需使用 md2pdf.py）；→ ★ ☆ 符号在 Palatino 中可能警告，会通过 CJK 字体回退渲染，可忽略；ASCII art 图表渲染为代码块。
- 若通过 pandoc 将 HTML 管道转为 Markdown，建议使用 pandoc --wrap=none input.html -o output.md，以避免图片和表格的换行相关解析问题。
依赖
pip install reportlab --break-system-packages 可选公式渲染：pip install matplotlib --break-system-packages
推荐 Ubuntu/Debian 字体： sudo apt install fonts-dejavu-core fonts-liberation fonts-freefont-ttf fonts-noto fonts-noto-cjk fonts-noto-color-emoji
pandoc 回退依赖：需要 pandoc 与带 XeLaTeX 的 TeX 发行版： brew install pandoc brew install --cask mactex-no-gui # 或 basictex