技能介绍

要解决什么问题

把 HTML 交给 wkhtmltopdf 或浏览器「打印为 PDF」，常见结果是布局漂移、Flex/Grid 对不齐、背景色被吃掉，或 SPA 还没渲染完就导出成空白页。若文档依赖 @page 定纸张与边距、Web 字体和 SVG，更需要与浏览器一致的渲染路径，而不是另一套半残的 HTML 引擎。

技能如何工作

本技能通过 Playwright 无头 Chromium 打开 HTML，再调用原生 PDF 导出。JavaScript 会执行，wait_until='networkidle' 用于尽量等动态内容就绪；与纯静态转换器不同，适合带交互渲染结果的页面。

核心入口是 skill 目录下的 scripts/html_to_pdf.py，典型流程：

单文件转换：指定 HTML 路径与输出 PDF
遵循 CSS @page：HTML 里写了 size、margin 时，配合 --prefer-css-page-size，让 PDF 尺寸与边距跟样式表一致
批量：对目录内多个 HTML 依次处理（每个文件独立起一个 Chromium 实例）
可选能力包括自定义页眉页脚、横向（宽表）、Letter 尺寸与边距等 CLI 参数

CSS 侧完整支持 @page、flexbox、grid、Web 字体、SVG、@media print；背景色需保留 print_background，勿误加 --no-background。

适用边界与注意点

路径：图片等相对资源需能解析（绝对路径或合适的 file:// 基础 URL），否则 PDF 会缺图
字体：系统无字体时优先用 Google Fonts 或 @font-face 嵌入
体积：高分辨率内嵌图会显著增大 PDF，需在 HTML 侧压缩
可选文字：扫描件或整页图片内容不可选中是正常现象，需 OCR 另处理
Linux/Docker：Chromium 依赖若缺失，需按 Playwright 文档安装系统库后再 playwright install chromium