技能介绍

解决的问题

把 Markdown 转成 PDF 的难点，通常不是命令是否存在，而是排版是否稳定。中文技术文档里常见的问题包括：正文混排时 CJK 字符显示为方框，代码块中的换行和缩进被 reportlab 压成空格，英文与中文连接处按空格断行造成割裂，封面、页眉页脚里的日期或声明无法渲染，表格列宽失衡，以及章节标题被合并成一行后无法生成目录书签。

工作方式

这个技能把 Markdown 作为结构化输入，用 Python reportlab 生成可交付的 PDF。它不是简单套用 CSS 打印模型，而是针对 CJK 文本和代码块做专门处理：

字体切换：为拉丁正文、CJK 正文和代码分别选择字体，Linux 下自动回退；
混排渲染：通过 _font_wrap() 处理段落文本，通过 _draw_mixed() 处理封面、页眉和页脚中的中英混合内容；
代码保真：esc_code() 先把换行和缩进转成可见排版符号，再叠加字体包装；
结构与导航：可生成封面、目录、侧边书签、水印、扉页图、封底图和版权声明；
主题输出：内置 warm-academic、classic-thesis、tufte、ieee-journal 等风格，也可用自定义主题文件控制背景、正文、强调色和代码底色。

边界与注意点

它最适合报告、白皮书、技术方案、教程等以标题、段落、列表、表格和代码块为主的 Markdown 文档。转换前需要确认主题、封面、扉页、水印和封底信息；如果选择 AI 生成扉页，应先生成图片并确认，再传入文件路径。对于高度自定义 HTML、复杂浮动布局、超长代码或特殊符号，仍建议先做小样本验证，再批量使用。