技能介绍

解决的问题

Markdown 在网页中通常可读，但用于打印、归档或正式交付时，版式容易不稳定：A4 边距、页码、中文字体、代码高亮、表格跨页和链接显示都会影响最终观感。mdtopdf 针对这类文档输出场景，把 Markdown 转换成一致的 PDF，而不是只依赖浏览器打印或临时样式。

技能如何工作

它基于 md2pdf 与 WeasyPrint，通过 @scripts/convert.py 读取 Markdown 文件，并套用 @assets/markdown.css。默认版式包括 A4 页面、25mm/20mm 页边距、页脚页码、中文衬线正文与无衬线标题。代码块使用等宽字体和 Pygments GitHub 风格高亮；表格支持边框、隔行色和跨页表头；引用、链接和分页也做了打印适配。若 Markdown 未以标题开头，可用 --title 注入标题；相对路径图片依赖 base_url，转换脚本会将其设置为 Markdown 文件所在目录。
它也支持扩展默认样式：可传入自定义 CSS，或直接调用 Python API 调整样式、标题、字体和分页行为。默认启用 GFM tables、pymdownx.superfences、脚注、智能引号等扩展，适合含表格、代码块、脚注和中文正文的技术文档。

适用边界与注意点

该技能适合把 Markdown 输出为正式 PDF，不适合需要 JavaScript 渲染、交互式组件或复杂网页排版的场景。中文字体缺失可能显示为方块字，需要环境提供 CJK 字体；WeasyPrint 依赖的系统库缺失会影响运行；资料中标注的 str | None 场景需要 Python 3.10+。自定义样式时应覆盖或扩展默认 CSS，并确认图片路径可解析，避免 PDF 空白或图片缺失。