HTML to PDF 是一个把 HTML 文件渲染为 PDF 的命令行工具，底层使用无头 Chromium，因此浏览器支持的 @page、flexbox、grid、webfonts、SVG、@media print 和 JavaScript 都能正常工作。
用途与模式选择
使用前首先要确定模式，这是最关键的一步。输入为报告、单页说明、讲解材料、仪表盘等可滚动文档时，使用 --mode page（默认）；输入为幻灯片、且幻灯片元素带有 class="slide" 时，使用 --mode slides。如果对幻灯片误用 page 模式，会得到纸张尺寸、纵向、把 1920x1080 画面压缩进去的 PDF，并且除当前激活页外其余页面可能为空白，因为入场动画依赖幻灯片只在当前页设置的类。资料中给出的实测例子是：四页幻灯片在 A4 纵向下有三页为空。slides 模式会依次以舞台分辨率展示每张幻灯片，把入场动画固定到完成状态，逐张捕获并合成为 16:9 的 PDF。若不确定文件属于哪种模式，可以搜索 class="slide" 是否出现在重复元素上。
运行方式
基本命令为：node "${CLAUDE_PLUGIN_ROOT}/skills/html-to-pdf/scripts/html-to-pdf.mjs" report.html。默认输出为与输入同路径、扩展名为 .pdf 的文件。也可以传入第二个路径指定输出，或一次传入多个 .html 输入进行批量转换。首次运行会把 Playwright 安装到 ~/.workhub/visuals-playwright，需要下载 Chromium，大约耗时一分钟，不会向项目目录安装任何内容。建议提前告知用户这一停顿。若自动安装失败，可回退到 npm install -g playwright 与 npx playwright install chromium。
文档模式（--mode page）
应先阅读文件。如果文件声明了 @page，应尊重它，使用 --prefer-css-page-size --outline report.html report.pdf。--outline 会根据标题生成 PDF 书签，使长报告便于导航，建议在文档具有真实标题结构时使用。Chromium 从带标签的结构树推导大纲，因此 --outline 会自动开启 --tagged；如果只把 --outline 传给 Playwright，会得到没有书签也没有警告的 PDF。若 CSS 中没有 @page，则显式设置纸张，例如 --format A4 --margin-top 20mm --margin-bottom 20mm --margin-left 18mm --margin-right 18mm doc.html。页码可放在页脚模板中，例如使用包含 pageNumber 与 totalPages 的 footer-template。宽表格旋转后更易阅读，可使用 --landscape。
幻灯片模式（--mode slides）
命令示例为 --mode slides deck.html deck.pdf。每张幻灯片会成为一页 1920x1080 的页面，动画会被压平为完成状态，交付时应说明这一点，避免用户对动效消失感到意外。资料提到，18 页幻灯片大约 20MB；超过约 10MB 时，可提供 --compact（1280x720），通常能把体积减半且在阅读距离下无明显损失。
可用选项
--mode page|slides 选择模式；--format FORMAT 指定纸张（默认 A4，可选 Letter、Legal、A0-A6）；--landscape 横向；--prefer-css-page-size 遵循 CSS 中的 @page 尺寸与边距；--margin-top|-right|-bottom|-left DIM 设置边距（如 20mm、1in、72pt）；--outline 从 h1-h6 生成 PDF 书签；--tagged 生成无障碍标签；--scale N 缩放系数（默认 1.0）；--no-background 省略背景色与图片；--header-template HTML 与 --footer-template HTML 设置页眉页脚（page 模式）；--compact 以 1280x720 捕获幻灯片；--width N / --height N 指定捕获尺寸（slides 模式）；--quiet、-q 抑制进度输出。
完成与排错
完成后应报告输出路径与大小，并说明被压平的内容（动画、交互、主题切换等）。除非用户要求，不要打开 PDF。常见问题包括：幻灯片页面为纵向且多数空白，原因是误用 page 模式，应改用 slides；提示 no .slide elements found，说明不是固定舞台幻灯片或类名不同，应改用 page 模式或重命名类；背景色缺失，可能是传了 --no-background 或页面没有打印规则，应去掉该标志或添加 print-color-adjust: exact；@page 规则被忽略，应添加 --prefer-css-page-size；字体异常，通常是本地未安装该字体，应使用 webfont 或通过 @font-face 嵌入；图片缺失，多因 src 使用绝对文件系统路径，应改为相对路径，脚本会通过 HTTP 提供该目录；空白页，可能是内容在 networkidle 之后才渲染，应让页面在 load 时完成工作而非依赖定时器；文本不可选，说明内容是栅格图像，属于预期行为，只有 OCR 能改变。代理环境下安装失败，通常是 npm 或 Chromium 下载被阻断，需要在允许的网络中手动安装 Playwright。