html-deck

HTML 幻灯片到 PDF 工作流

使用无头 Chrome 构建精美、可直接用于演示的 HTML 幻灯片，并将其转换为极其清晰的 PDF。

何时使用

• 根据程序文档、笔记或大纲创建新的幻灯片。
• 将粗糙的内容转换为专业的演示文稿。
• 生成具有精确页面尺寸的 HTML 幻灯片 PDF 版本。
• 构建包含应用截图或产品视觉素材的幻灯片。

进度清单

Deck Build Progress:
- [ ] Phase 1: Slide skeleton (HTML + CSS foundation)
- [ ] Phase 2: Content population (slides from source material)
- [ ] Phase 3: Visual polish (spacing, typography, layout fixes)
- [ ] Phase 4: Print-safe CSS
- [ ] Phase 5: PDF conversion (use bundled script; do not reimplement)
- [ ] Phase 6: Verification (screenshot comparison)

阶段 1 — 幻灯片骨架

使用 Domo 主题 — 强制第一步

1. 阅读 references/domo-theme.md — 其中包含一个完整、可直接复制粘贴的 HTML 骨架，可生成与 Domo 模板完全一致的幻灯片。
2. 阅读 references/assets/logo-data-uri.txt — 其中包含以 base64 PNG data URI 表示的 Domo 实际 logo。将骨架中每个 LOGO_DATA_URI 占位符替换为此值。
3. logo PNG 也位于 references/assets/domologo.png。

不要跳过此步骤。 从主题文件中复制完整骨架，然后在其基础上构建幻灯片。每张内容幻灯片必须包含：

• 页眉：<div class="slide-header">，包含 <h1>、.subtitle 以及 .header-line（细灰色分隔线 — 必需）
• 内容：<div class="slide-content has-bg"> — 始终使用 has-bg 以获得灰色 #DDE5ED 背景（这是 Domo 的外观；内容会自动垂直居中）
• 页脚：<div class="slide-footer">，包含 .confidential（左侧）、.footer-line（中间）以及带 <img src="LOGO_DATA_URI"> 的 .domo-badge（右下角 — 必需）

尺寸

标准 16:9 宽屏：--slide-w: 1024px; --slide-h: 576px;

内容区域定位

has-bg 类会自动处理定位（position:absolute; top:90px; bottom:52px）并实现垂直居中（display:flex; justify-content:center）。不要用内联样式覆盖这些设置。

阶段 2 — 内容填充

幻灯片类型模式

表格幻灯片 — 使用带标记列标题的样式化 <table>。在内容密集的幻灯片上保持单元格内边距紧凑（6px 10px）。

流程/管道幻灯片 — 水平 flex 排列的方框，用箭头分隔符（▶）分隔。使用彩色左边框或上边框来区分阶段。

卡片网格 — 等宽卡片的 flex 行。每张卡片使用 flex:1、一致的内边距以及微妙的背景色（#F6F8FA）。

架构图 — 嵌套的 flex 容器。用彩色卡片组标记每一层（例如 "INTELLIGENCE LAYER"、"STORAGE"、"COMPUTE"）。

截图展示 — 一张主图居中，或两张并排且 max-width:48%。应用 border-radius:8px 以提升精致感。不要使用 box-shadow（反正会被打印 CSS 移除）。

信息框 — 主内容下方成对出现的方框。使用 display:flex; gap:32px，每个方框使用 flex:1。

排版层级

元素	大小	字重
幻灯片标题（h1）	28px	800
副标题	11px	700
章节标签	10px	700，大写，字母间距 2px
正文	13–14px	400
表格文字	11–13px	400
细字/说明文字	9–10px	400

颜色约定

使用 CSS 变量以保持一致。在 :root 中定义品牌色、强调色和文本色调。

阶段 3 — 视觉润色

间距规则

1. 内容绝不能触及页脚。 .slide-content 上的 bottom:52px 创建了一个 52px 的排除区域。如果内容仍然重叠，请减小出错元素上的 margin-top、padding、gap、font-size 或 line-height。

2. 页眉与内容之间的间隙。 .slide-content 上的 top 值控制页眉下方的间距。典型值：88–100px。如果副标题文本与内容碰撞，请增大该值。

3. 密集幻灯片。 当一张幻灯片同时包含表格和信息框时，使用紧凑值：

   • 表格单元格内边距：4px 10px
   • 信息框内边距：5px 12px
   • 卡片之间的间隙：3–5px
   • 字体大小：从默认值缩小 1px

4. justify-content:center 注意事项。 垂直居中可能会将较高的内容推到 bottom 之外。在内容繁重的幻灯片上移除它，让内容从顶部开始流动。

图片处理

• 对 src 路径中的空格进行 URL 编码：Sample%20Assets/file.png。
• 避免在文件名中使用特殊 Unicode 字符。如有需要，复制到干净的文件名。
• 使用 max-width:100%; max-height:100% 和 object-fit:contain 在内容区域内自动调整大小。

阶段 4 — 打印安全 CSS

通过 Chromium 打印管线进行的 PDF 渲染与屏幕渲染对 box-shadow 的处理方式不同。阴影在 PDF 输出中会显示为厚重的深色块。

必需规则（已包含在上方骨架中）：

@media print {
  *, *::before, *::after {
    box-shadow: none !important;
  }
}

这仅在打印时剥离所有阴影。HTML 浏览器视图保留其阴影。

其他打印注意事项：

• .slide 上的 page-break-after: always — 每页一张幻灯片。
• page-break-inside: avoid — 防止幻灯片中间分页。
• body 上的 background: white — 没有灰色查看器背景。

阶段 5 — PDF 转换器

不要从头重写转换器。 本技能附带一个维护中的脚本：references/convert-to-pdf.js。将其复制到用户的项目中，或在安装后从技能目录按路径运行它。

npm install puppeteer-core
node convert-to-pdf.js path/to/deck.html path/to/deck.pdf
# optional second arg omitted => writes next to the HTML with .pdf extension

该脚本使用 puppeteer-core 搭配系统 Chrome 二进制文件（而非捆绑的 Chromium），与下面的方法一致。

关键设置（已在脚本中实现；仅在有明确理由时更改）：

• deviceScaleFactor: 2 — 视网膜级清晰文本。
• printBackground: true — 保留彩色背景。
• margin: { top: 0, ... } — 幻灯片周围无额外空白。
• width/height 必须与 --slide-w/--slide-h 完全匹配。
• 在捕获之前等待 document.fonts.ready — Google Fonts 必须完成加载。

package.json 设置

{
  "scripts": { "pdf": "node convert-to-pdf.js" },
  "dependencies": { "puppeteer-core": "latest" }
}

使用 puppeteer-core（而非 puppeteer）：完整的 puppeteer 包在安装时会下载自己的 Chromium（约数百 MB）并使用该浏览器；puppeteer-core 仅是自动化库，期望你向现有的 Chrome/Chromium 传递 executablePath（此脚本会查找系统 Chrome）。安装更小、只需更新一个浏览器、CI/缓存问题更少。

阶段 6 — 验证

对每个 HTML 幻灯片和每个 PDF 页面进行截图，然后进行视觉比较。

快速验证脚本

// Screenshot slide N from the HTML
const box = await page.evaluate((idx) => {
  const el = document.querySelectorAll(".slide")[idx];
  const r = el.getBoundingClientRect();
  return { x: r.x, y: r.y, width: r.width, height: r.height };
}, slideIndex);

await page.screenshot({ path: `html_slide_${n}.png`, clip: box });

检查内容

• 页数与幻灯片数量匹配。
• 任何幻灯片上都没有内容被页脚裁剪。
• 字体已加载（不是后备衬线/无衬线字体）。
• 所有图片均正常渲染（没有损坏图片图标或替代文本）。
• 卡片或图片周围没有深色色块/阴影块。
• 背景颜色和渐变得到保留。
• 页面边缘极其锐利（没有多余的边距或空白）。

常见问题

现象	原因	修复方法
内容与页脚重叠	未设置 bottom，或高内容上使用了 justify-content:center	在 .slide-content 上设置 bottom:52px；在内容密集的幻灯片上移除垂直居中
PDF 中元素周围出现深色块	box-shadow 在打印时渲染不同	添加 @media print { * { box-shadow: none !important; } }
图片无法加载	文件路径中包含空格或 Unicode	对空格进行 URL 编码（%20）；将文件复制为干净的文件名
字体回退到衬线字体	未等待 networkidle0，或字体被阻止	等待 document.fonts.ready；确保 Google Fonts URL 正确
找不到 Chrome	Puppeteer 无法定位浏览器	使用 puppeteer-core + executablePath 指向系统 Chrome
页面周围有多余空白	PDF 边距未归零	设置 margin: { top: 0, right: 0, bottom: 0, left: 0 }
PDF 中文字模糊	设备缩放因子过低	在 viewport 中设置 deviceScaleFactor: 2

检查清单

• 幻灯片尺寸与 --slide-w 和 --slide-h CSS 变量匹配
• 每个 .slide-content 都设置了 bottom:52px 以避开页脚
• @media print 块移除了所有 box-shadow 值
• 在 .slide 上设置了 page-break-after: always 以用于打印
• 转换器使用 puppeteer-core 并指定系统 Chrome 路径
• PDF 选项中设置了 printBackground: true 且边距为零
• 设置 deviceScaleFactor: 2 以获得视网膜级质量
• 在捕获 PDF 前等待字体加载完成
• 图片路径已进行 URL 编码（无原始空格）
• 已在封面、内容密集的幻灯片和截图幻灯片上完成视觉验证