Skip to content
Back to search

html-to-editable-pptx

Convert HTML slide decks to truly editable PPT / .pptx - text stays native PowerPoint textboxes, not screenshots. Agent Skill (Claude Code / Cursor / Codex / opencode) + plain Python CLI.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hasasasa--html-to-editable-pptx/badge.svg)](/listings/hasasasa--html-to-editable-pptx)

HTML

<a href="/listings/hasasasa--html-to-editable-pptx"><img src="/api/listings/hasasasa--html-to-editable-pptx/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install

In a Claude Code session, just hand Claude the repo URL:

Install this skill for me: https://github.com/Hasasasa/claude-skill-html-to-pptx

Claude will `git clone` it into the right skills directory for your platform (macOS / Linux: `~/.claude/skills/`; Windows: `%USERPROFILE%\.claude\skills\`) and walk you through installing Python 3.10+, Playwright, and dependencies. System-level steps will still ask for your confirmation.

Use

After install, ask in plain language:

Convert D:\path\to\deck.html to pptx

Full skill invocation rules, audit mode, and fix discipline are in [SKILL.md](SKILL.md).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 386 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: html-to-pptx
  3. description: 当用户想把 HTML 幻灯片转成 .pptx 时触发——"HTML 转 PPT"、"网页幻灯片转 pptx"、"把这个 deck 转成 ppt"、"给同事一份 ppt 副本"、"汇报不方便放浏览器"、给了 .html 路径 + 提到 ppt/pptx/演示/幻灯片。保留矢量文字可编辑、字体按需嵌入、复杂装饰自动走截图兜底;不依赖 reveal.js / 自写 deck 等具体框架。
  4. ---
  5. # html-to-pptx
  6. ## 何时触发
  7. 用户说出下列任一意图:
  8. - "把这个 HTML / 网页 deck 转成 PPT / pptx"
  9. - "做了 HTML 幻灯片,要给同事一份 ppt"
  10. - "汇报现场不方便放浏览器,想要 ppt 文件"
  11. - 已有 HTML 文件路径 + 提到 ppt / pptx / 演示 / 幻灯片
  12. ## 调用
  13. `<skill_dir>` 是这个 skill 安装路径(通常 `~/.claude/skills/html-to-pptx/`,Windows 上是 `%USERPROFILE%\.claude\skills\html-to-pptx\`)。下面命令里的 `<skill_dir>` 替换成实际路径,或者先 `cd <skill_dir>` 再直接 `python convert.py …`。
  14. ```bash
  15. python <skill_dir>/convert.py <input.html>
  16. ```
  17. - 默认输出到与输入同目录的 `<input>.pptx`
  18. - 字体完全按需:HTML 用到的字体在 convert 时从 Google Fonts 拉取并 subset 嵌入,缓存到 `%LOCALAPPDATA%\html-to-pptx\fonts\` 或 `~/.cache/html-to-pptx/fonts/`,下次同名字体秒复用
  19. - HTML 含 CJK 字符会自动种子 Noto Sans SC + Noto Serif SC(首次约 40 MB / ~30s 下载并 instance 静态 Regular/Bold,之后命中 cache)
  20. - GF 没有的家族会回退到 viewer 系统字体并打印 warning
  21. | 选项 | 含义 |
  22. |---|---|
  23. | `--out <path>` | 自定义输出 .pptx 路径 |
  24. | `--keep-screenshots` | 同时保留每页 HTML 参考截图 + `preflight.json` |
  25. | `--no-embed-fonts` | 跳过字体嵌入。文件更小但换机会回退到系统字体 |
  26. | `--no-preflight` | 关闭 Stage 1 风险预扫 |
  27. | `--no-verify` | 关闭 Stage 5a 结构化自检 |
  28. | `--no-visual-audit` | 关闭 Stage 5b 视觉 audit 物料产出。日常不要关 |
  29. | `--install-user-fonts` | 把自动解析到的非 CJK 字体装到用户字体目录(让 WPS 能正确渲染)。Win/macOS/Linux 都支持。**必须先问用户**,见下方"配置确认"章节 |
  30. | `--only-slides N,N,N` | **增量重跑**。逗号分隔的页号(1-based)。measure 只跑指定页 + 与上轮 cached measurement 合并;assemble/embed 仍全量;Stage 5a 只渲指定页;Stage 5b 只重建指定页的 compare 图——其它页全部复用上轮缓存。audit 迭代轮专用,详见下方"增量重跑"章节 |
  31. | `--cleanup` | 不做转换。删 input.pptx 旁的 audit / measurement / preflight 工作物,只保留 .pptx 和 audited.html。**最终交付前用**,见下方"工作流"末步 |
  32. ## 工作副本(原 HTML 不动)
  33. 第一次 `python convert.py <input>.html` 跑完,convert.py 自动 cp 一份 `<input>.audited.html` 到源 HTML 同目录。机制:
  34. - **所有 audit 修复改 `audited.html`,不改源 HTML**
  35. - 后续轮 convert(含 `--only-slides`)input 用 `<input>.audited.html`,输出仍是 `<input>.pptx`(自动去掉 `.audited` 后缀)
  36. - `audited.html` 已存在 → 复用,不覆盖(保留上轮修复)
  37. - agent 误传源 HTML 当 input → convert.py 内部检测后切到 audited.html 兜底
  38. - cleanup 不删 audited.html(视为可交付副产物,跟 `.pptx` 一组交付)
  39. - 想从头开始 → 手动删 audited.html 后重跑
  40. ## 配置(`.config.local.toml`)
  41. skill 根目录下可选的本机偏好文件,gitignored,每用户一份。当前有三类偏好:
  42. ```toml
  43. [fonts]
  44. auto_install = "ask" # "yes" 自动装、"no" 永不装、"ask" 由 agent 询问
  45. [cleanup]
  46. default = "clean" # "clean" 工作流末步自动 cleanup、"keep" 保留 audit 产物
  47. [audit]
  48. mode = "ask" # "triage" / "page" / "manual" / "ask" 由 agent 询问
  49. ```
  50. - 文件 / key 缺失 → 走默认(同上)
  51. - 模板:`<skill_dir>/.config.local.toml.example`
  52. - `fonts.auto_install` 由 convert.py 强制读取并应用(=yes 自动加 `--install-user-fonts`、=no 自动忽略)
  53. - `cleanup.default` 由 agent 在工作流末步读取决定行为
  54. - `audit.mode` 由 agent 在第一次 convert 前确认;Stage 5b 后按该值执行审查:
  55. - `"triage"` → 主 agent 自己看 `audit_contact_*.png` 总览分流,再派 sub-agent 看入围页单图,节省 token
  56. - `"page"` → 每个目标页都派 sub-agent 看单页 `slide_NN_compare.png`,覆盖最严
  57. - `"manual"` → 只生成审查物料,交给用户人工核查;用户反馈问题后再修
  58. - `"ask"` 或缺失 → agent 通过 AskUserQuestion 收集偏好后改写此项(默认)
  59. - **首次使用**:agent 通过 AskUserQuestion 收集 `fonts.auto_install` 和 `audit.mode` 后**自己 Write 这个文件**——用户不用手动建
  60. ## 配置确认(第一次 convert 之前完成)
  61. 两条偏好要在第一次 convert 之前确认:`fonts.auto_install` 和 `audit.mode`。流程相同,差别只在触发条件和问法。
  62. ### 通用流程
  63. 每条偏好独立按下面顺序判定:
  64. 1. Read `<skill_dir>/.config.local.toml`,看对应字段:
  65. - 合法非 `ask` 值 → 按该值走,会话内不再问
  66. - `ask` 或文件 / 字段缺失 → 走"触发判定 + ask"
  67. 2. CLAUDE.md / 全局指令写明了等同值的,按写明值走,并补写 config(保持单一事实源)
  68. 触发后 AskUserQuestion 问一次,**两条都要做**:
  69. - **写入** `<skill_dir>/.config.local.toml` 对应字段为用户答复(不写 `ask`,否则下次会话还会再问)
  70. - 本次会话同时按答复走
  71. 写 config 时:文件**不存在** → Write 整文件落盘([fonts] [cleanup] [audit] 三段模板);文件**已存在** → 用 Edit 做单行 replace(只改这一个字段),**不要** Write 重写整文件,否则会吞掉用户其它自定义 key。
  72. 同一会话两条都触发 → 合并到同一条 AskUserQuestion 里一次问完。
  73. ### `fonts.auto_install` —— 字体安装
  74. PowerPoint COM `slide.Export()` 和 WPS Office 都不读 pptx 内嵌的裸 TTF——audit 渲染和 WPS 都回退到系统字体。装到用户字体目录后两者都按系统字体走。目录(均为用户级,可手工删):
  75. - Windows: `%LOCALAPPDATA%\Microsoft\Windows\Fonts\` + HKCU 注册
  76. - macOS: `~/Library/Fonts/`
  77. - Linux: `~/.local/share/fonts/` + `fc-cache -f`
  78. **触发判定**:看 HTML `<head>` 的 `<link href="...fonts.googleapis.com/...">` / `@import url(https://fonts.googleapis.com/...)` / `<style>` 里 `font-family:` 出现的字体名:
  79. - **触发**:任何 GF / 自托管字体(Bricolage Grotesque、DM Sans、Inter、Space Grotesk、Caveat 等)
  80. - **不触发**:只用系统字体白名单(Arial、Times New Roman、Helvetica、Helvetica Neue、Courier、system-ui、-apple-system、BlinkMacSystemFont、SF Pro、Microsoft YaHei、SimSun、PingFang、Hiragino)
  81. 按答复:同意 → 加 `--install-user-fonts`;拒绝 → 不加。
  82. ### `audit.mode` —— 视觉审查模式
  83. 三种模式 `triage` / `page` / `manual`(含义见上方 "配置" 章节)。**每次会话第一次 convert 之前都判定**(不依赖 HTML 内容触发)。AskUserQuestion 用单选题,选项即三种模式。
  84. ## 工作流(强制)
  85. convert.py 跑完不等于交付完成。完整流程:
  86. ```
  87. convert.py(首轮自动 cp <input>.audited.html,所有修复改这个副本)
  88. → Stage 5a 结构化自检(OOXML 扫描,给提示)
  89. → Stage 5b 视觉 audit 物料 — 需要 PowerPoint COM 或 LibreOffice 渲染器
  90. → 读 `audit.mode` 决定审查方式:triage / page / manual
  91. → 【agent audit】
  92. triage 模式:主 agent 读 contact sheet 分流 → sub-agent 看入围页单图 → 合并写 audit_findings.md
  93. page 模式:全量 sub-agent 看单页 → 合并写 audit_findings.md
  94. manual 模式:把 audit 物料交给用户,等待用户人工反馈
  95. → 按 finding 逐项做最小局部修改,目标是 audited.html(见下"修复纪律")
  96. → 一批 finding 改完后 `convert.py <input>.audited.html --only-slides <被改页号>` + 只对 fresh 页重审(见下"增量重跑")
  97. → 所有页 OK 或仅剩 LOW
  98. → 【若撞到 HTML 反模式 / 新 OOXML 边界】沉淀到 lessons-learned,见下方"沉淀 HTML 问题与 OOXML 边界"
  99. → 读 `<skill_dir>/.config.local.toml` 的 `cleanup.default`:
  100. "clean"(缺省)→ 直接 `python convert.py <out>.pptx --cleanup`,不问用户
  101. 清完目录剩:<input>.html(源,未动)+ <input>.audited.html(修复版)+ <out>.pptx
  102. "keep" → 跳过 cleanup,audit 产物全部保留
  103. → 把 .pptx 路径交付给用户(audited.html 作为修复版 HTML 一同交付)
  104. ```
  105. ### 矢量优先原则(强制)
  106. 能用 PPT 原生 text / shape / line 表达的内容,优先保持可编辑:普通背景色、普通四边框、单边线、简单矩形/椭圆、简单 `::before` / `::after` 线框都应走 PPT shape。
  107. `deco_snapshot` 只兜底 OOXML 难表达的装饰(命中条件 + 完整档位定义 + 截图/矢量层协同机制见 [`references/supported-css.md`](./references/supported-css.md))。不要为了省事把普通线条、图表轴线、简单边框统一截图——这会牺牲 PPT 可编辑性,也会让后续局部修复变难。
  108. ### 渲染器要求(Stage 5b 前置条件)
  109. Stage 5b 视觉 audit 需要把 .pptx 渲染成 PNG,依赖:
  110. - **PowerPoint COM**(Windows + Office + `pywin32`),或
  111. - **LibreOffice**(跨平台,配 `pip install pdf2image`)
  112. 任一可用就能跑 audit。convert 输出里看到 `[self-check] 跳过:找不到可用的 pptx 渲染器`,说明两个都没装——此时 audit **不会**产出 compare 图,Stage 5b 直接跳过。
  113. **这种情况下 agent 必须 ask 用户**(不要静默交付未审计的 pptx):
  114. > "你机器上没装 PowerPoint 也没装 LibreOffice,视觉 audit 跑不了,PPT 可能有看不出的视觉 bug。三个选择:
  115. > 1. 装 LibreOffice(推荐,跨平台,2-3 分钟):`winget install LibreOffice.LibreOffice`(Windows)/ `brew install --cask libreoffice`(mac)/ `apt install libreoffice`(Linux),然后 `pip install pdf2image`,重跑 convert
  116. > 2. 跳过 audit 直接交付(接受 PPT 可能有视觉 bug 的风险)
  117. > 3. 在已经装了 Office 的另一台机器上重跑"
  118. 用户选 1 → 等他装完重跑;选 2 → 加 `--no-visual-audit` 跑一遍,把告知风险后交付;选 3 → 把当前目录 + HTML 发给他。
  119. ### 视觉 audit 模式(config,前提:5b 跑起来了)
  120. 执行视觉审查前读取 `<skill_dir>/.config.local.toml` 的 `[audit].mode`。正常应在第一次 convert 前通过上方 "配置确认" 完成询问;如果到这里 mode 还是 `"ask"`(说明 agent 漏问了),立刻按 "配置确认" 章节询问用户再继续。
  121. 每个 mode 的具体含义见上方 "配置" 章节;这里只列适用场景:
  122. | mode | 适用 |
  123. |---|---|
  124. | `triage` | 默认,节省 token |
  125. | `page` | 最终交付前、关键客户、用户要求最严 |
  126. | `manual` | 用户想自己看 |
  127. `triage` 的分工很明确:**第 1 轮 contact pass = 主 agent 自己看缩略图分流(廉价,上下文已含源 HTML / Stage 5a / preflight)**;**第 2 轮 detail pass = 把入围页派 sub-agent 看单页 compare 图**。不能只凭缩略图判 HIGH/MID finding;要报 finding 必须经第 2 轮 sub-agent 单页确认。
  128. ### audit 分发与 compare 图读取规则
  129. `page` 模式所有页都走 Claude `Agent(...)` sub-agent 并行 dispatch。`triage` 模式只有第 2 轮入围页走 sub-agent;第 1 轮 contact sheet 由主 agent 自己 Read,不派 sub-agent。
  130. 主 agent 主动读 compare 图的场景仅限以下五种:
  131. - `triage` 第 1 轮读 `audit_contact_*.png` 总览分流
  132. - **针对性修复的验证轮**:本轮 fresh 页 ≤ 2 且改动未涉及全局 CSS → 主 agent 直读 fresh 页单图复核已知 finding + 扫该页新回归,**不派 sub-agent**(sub-agent 一轮 2-3 分钟,直读只要几秒)。fresh 页更多或有全局变更仍走 sub-agent
  133. - finding 描述含糊 / 与源代码冲突无法定位时,读对应**单页** `slide_NN_compare.png`
  134. - sticky 命中前确认读单页
  135. - 用户点名反馈某一页读单页
  136. 除此之外不逐页 Read compare 图。
  137. batch 按 wall-clock 优化拆小并行(sub-agent 串行读大图是延迟主因,多个小 batch 并行发满比一个大 batch 快一倍以上):
  138. | slide 数 | 策略 |
  139. |---|---|
  140. | ≤ 2 | 1 个 batch |
  141. | 3-20 | 每 batch 2 页,全部并行发 |
  142. | > 20 | 每 batch 3 页(控制 agent 总数) |
  143. 完整 sub-agent 调用模板 + 检查清单 + findings 格式见 `<out>_audit/audit_prompt.md`。多个 `Agent(..., run_in_background: true, subagent_type: "general-purpose")` 调用塞在主 agent 同一条 message 里才并行。
  144. sub-agent 只返回 findings 文本(page 模式含每个目标页的 `## page NN` 块;triage 细看批次含每个被放大复核页的块),主 agent 统一合并写 `audit_findings.md`——并发写会互相覆盖。
  145. 每条 finding 必须点名稳定元素短名,并描述"HTML 半图实际状态;PPT 半图差异"。只报告 PPT 相对 HTML 新增或放大的视觉问题;HTML 半图本身已有的问题不算转换 finding。
  146. ### 与 sub-agent 并行的主 agent 准备(强制)
  147. 发起 page 模式或 triage 第 2 轮 detail sub-agent 时,Agent 调用用 `run_in_background: true`,并在**同一条 message** 里同时发:
  148. ```
  149. Agent(run_in_background: true, subagent_type: "general-purpose", description: "Audit slides 1-4", prompt: ...)
  150. Agent(run_in_background: true, subagent_type: "general-purpose", description: "Audit slides 5-9", prompt: ...)
  151. Read(file_path: "<deck>/template.html")
  152. Read(file_path: "<skill_dir>/references/lessons-learned.md")
  153. Grep(pattern: "class=\"slide |data-slide=", path: "<deck>/template.html",
  154. output_mode: "content", -n: true)
  155. ```
  156. 每个 sub-agent prompt 里必须直接写入本批 `slide_NN_compare.png` 绝对路径、deck HTML 路径、`lessons-learned.md` 路径(适用范围见上方"视觉 audit 模式"章节);不要假设主 agent 的 Read / Grep 输出会自动传给 sub-agent。
  157. 只发"无论 findings 是什么都用得上"的准备——不要预测 findings 提前改 HTML。
  158. ### 修复纪律(针对 finding,不追根因)
  159. 收到 `audit_findings.md` 之后,**一轮里把本轮所有 finding 都改完,再一次性重跑 convert + audit**——不是改一个跑一次。一轮 = 一批 HTML 编辑 + 一次 convert + 一次 audit。
  160. 拿到 findings 之后:
  161. - **不**常规自己 Read compare 图(findings 已经把症状写明);三种例外读单页复核见上方 "audit 分发与 compare 图读取规则" 章节
  162. - **不**读 `measure.py` / `assemble.py` / 任何 skill 内代码找根因
  163. - 直接打开 `audited.html` 按 finding 逐条改
  164. 每个 finding 内部做最小局部 HTML 修改:
  165. - 每个 finding 只改"让它消失"的那一处,改完进下一个 finding(**继续改 HTML**,不是重跑 convert)
  166. - **不**追溯"为什么字体回退 / 为什么布局偏移"的深层根因
  167. - **不**做"我顺手把 .footer 也改成绝对定位"这种 finding 列表外的优化
  168. - **不**跨 finding 做结构性重构("统一把所有 slide 的 font-family 显式声明"≠ 单个 finding 的最小修复)
  169. - 同一 finding 在**连续两轮**(上一轮 + 本轮)都出现 → sticky 命中,停下来告诉用户,**不要**继续扩大改动面。判定 key = `(页号, 视觉元素短名)`:
  170. - 措辞 / 严重度 / HIGH↔MID 切换都**不重置**判定。例:`(page 5, take 字号)` 在 round 6 被描述成"偏小"、round 7 被描述成"严重不足" → 同一 sticky key,round 7 即命中
  171. - 只有"页号 + 元素"都不重合才算新 sticky key
  172. - **隔轮恢复**:若 round 6 出现、round 7 消失、round 8 又出现 → 不算 sticky(round 7 缺席视为问题已修,round 8 是新回归)
  173. - 命中 = 本轮**不修**该 finding、列入 skill 边界候选告诉用户,本轮其他 finding 照修
  174. 实施:每轮合并完 `audit_findings.md`、动 Edit 之前,必须先 Read 上一轮 `audit_findings.md`(首轮无)做两两比对——本轮和上轮**都**出现的 key 即命中。命中的 finding 单独列出来交给用户判断,不再进本轮编辑队列。
  175. 本批 finding 改完一次性 `python convert.py <input>.audited.html --only-slides <被改过的页号>`。
  176. 判定标准:你的 diff 行数 ≤ findings 数 × 3 行。超过这个量级说明在"乱发挥"。
  177. ### 增量重跑(`--only-slides`)
  178. audit 第 2 轮起用,首轮全量。
  179. ```bash
  180. python convert.py <input>.audited.html --only-slides 2,7,12
  181. ```
  182. 增量覆盖 measure / Stage 5a 渲染 / Stage 5b compare 图,仅对列出的页 + 缓存缺失的页执行;assemble / embed_fonts 仍全量。`audit_index.json` 标 `incremental_mode: true`、`fresh_indices`、`cached_indices`、每页 `fresh: true/false`。
  183. 增量轮的 audit 目标页只取 `fresh_indices`。`page` 模式直接分发这些页;`triage` 模式先在这些页范围内分流,再把入围页发给 sub-agent。
  184. 前提:上轮的 `<out>_audit/` 目录还在。cache 缺失自动回退全量;HTML 页数变化自动检测并回退全量 measure。
  185. **不能用 `--only-slides` 的情况**(视觉溢出列出的页,缓存假阴性):
  186. - 全局 CSS(`<style>`、根选择器、`.slide` 通用样式)变更
  187. - 新增 / 删除字体(@import、font-family 声明变更)
  188. - deck-level token(背景、主题色、间距)变更
  189. - 任何影响其它页布局的全局变量变更
  190. 这几类不带 flag 全量重跑。判断不准 → 全量重跑总是安全的。
  191. ## 沉淀 HTML 问题与 OOXML 边界(强制)
  192. 你的角色是**调用 + 用法沉淀**,不是修 skill。发现 skill 内部 bug 时**不要原地改 measure.py / assemble.py**。
  193. 只沉淀两类:
  194. ### 1. HTML 写法问题(用户的 HTML 让转换失真)
  195. | 类别 | 判定 | 做什么 |
  196. |---|---|---|
  197. | 单次 case(只在这 deck 出现,改一两行 HTML 就好) | 单页特例 | 直接改 HTML 源;不沉,不通报 |
  198. | 通用 HTML 反模式(任何人写类似 HTML 都会踩) | 跨 deck | 改 HTML + 沉到 `references/lessons-learned.md` 的 "HTML 写法规避" 区 |
  199. ### 2. OOXML 表达力边界(PowerPoint / OOXML 天然不支持)
  200. 绝大多数装饰类 CSS(backdrop-filter / filter / mix-blend-mode / skew / box-shadow / gradient / `::before` `::after` **装饰用法**——空 content + bg-image / box-shadow 等)已经被"覆盖策略"里的 `hasComplexDecoration` 自动捕获走 deco_snapshot——**HTML 不用改**。`::before` `::after` **string content**(`content: "↑"` 等)走文字通道,详见 [`references/supported-css.md`](./references/supported-css.md) 第 1 档。
  201. 仍需 HTML workaround 的真边界(OOXML 文字层原生表达不了的):
  202. | 边界 | 替代通路 |
  203. |---|---|
  204. | 彩色 emoji(COLR/CPAL 字体) | Twemoji SVG `<img>`,走 img 通道嵌入 |
  205. | `background-clip: text` 文字渐变 | inline `<svg><text fill="url(#grad)">`,走 SVG 通道 |
  206. 撞到这两类 → 改 HTML 走替代通路 + 沉到 `references/lessons-learned.md` 的 "OOXML 边界" 区。
  207. 撞到不在上表的新 CSS 不支持 → **先看 `hasComplexDecoration` 是不是漏触发**(加一行触发条件即可),而不是改 HTML。详见 [`references/supported-css.md`](./references/supported-css.md) 的"加新支持的标准做法"。
  208. ### 看似 skill 内 bug 怎么处理(**不修不沉**)
  209. 发现某症状用同种 CSS 模式换 deck 还会撞、且不在已知 OOXML 边界内 → 这是 skill 抽象不到位。**不要原地改 skill 代码**。做这两件事:
  210. 1. 当前 deck **走 HTML 端 workaround** 把 finding 修掉,让用户拿到能交付的 PPT
  211. 2. **明确告知用户**:"发现一个看起来是 skill 内的通用 bug:[症状 + 触发 CSS 模式 + 当前 workaround]。建议作者按 issue 收录,让 skill 在 measure/assemble 里更通用地处理这种模式"
  212. ### 沉淀写到哪:本地副本 + 上游模板
  213. `references/lessons-learned.md` 是**每用户独立的本地工作副本**(gitignored)。首次跑 `convert.py` 时 `local_config.seed_lessons_learned()` 自动从模板 `lessons-learned.md.example`(committed)拷贝一份。机制和 `.config.local.toml` 一样。
  214. - **agent 排查 / 沉淀都读写本地 `lessons-learned.md`**——自由加 / 改 / 整理,无 git 噪声
  215. - 本地副本**永不被上游覆盖**——`git pull` 拉的是 `.example` 模板,不动你的工作副本
  216. - 想把某条沉淀上游:**作者手动把 entry 复制回 `lessons-learned.md.example`** 再 commit;选择性 curate,不是全推
  217. - 本地业务 / 特定客户专有写法 → 直接写在本地副本里就行,不会上游
  218. - lessons 条目只写可复用的症状、触发模式、规避规则;不要写具体本地文件名、模板名、页面号、客户名或源码文件名。具体实现位置、命令和代码细节留在 commit / issue / 主 skill 文档里
  219. **触发**:撞到通用 HTML 反模式 / OOXML 边界 → 加到本地 `lessons-learned.md` 对应表。每次 convert 都重读,立即生效。
  220. ## 覆盖策略(一句话)
  221. skill 内部把所有 CSS 翻译成四档输出:**矢量文字 → 矢量形状 → 栅格装饰(`deco_snapshot`)→ 媒体直传**。简单 bg-color / border / border-radius 走前两档(可编辑可搜索),box-shadow / gradient / filter / backdrop-filter / mix-blend-mode / 非对称圆角 / 裁切容器 + 旋转子 等命中 `hasComplexDecoration` 走第三档(栅格只截装饰像素,文字始终保留矢量画在截图之上)。
  222. 完整档位定义 / 触发条件 / 加新支持指南(矢量优先 → 截图兜底)→ [`references/supported-css.md`](./references/supported-css.md)。
  223. ## 流水线
  224. ```
  225. [1 输入识别/预扫] → [2 测量] → [3 组装] → [4 字体嵌入] → [5a 结构化自检] → [5b 视觉 audit]
  226. preflight.py measure.py assemble.py embed_fonts.py self_check.py visual_audit.py
  227. ```
  228. 各阶段动作 / 反假设规则 / 退出断言 / 新模板 checklist → [`references/methodology.md`](./references/methodology.md)。
  229. Stage 5b 产出 `<out>_audit/`(compare 图 + contact sheet + `audit_index.json` + `audit_prompt.md`)。**不做像素 diff** — 数字对局部 bug 不敏感、给假信心;视觉判断按 `audit.mode` 走 triage / page / manual。无渲染器时 5b 跳过,按上面"渲染器要求"小节 ask 用户。
  230. ## 调用前确认
  231. 1. 输入是单文件 HTML,含若干 slide 元素(`<section class="slide">` / `<div class="slide">` / `<deck-stage>` 子节点等都支持)
  232. 2. 不需要为用户配置切页机制 —— skill 自动识别
  233. 3. 用户已写好 HTML 才来调用,按要求转就行
  234. ## 报告
  235. | 用户反馈 | 处理 |
  236. |---|---|
  237. | 想加页 / 改文字 | 改源 `<input>.html`(不是 audited.html,那是 audit 修复版)→ 删 audited.html → 重跑 convert |
  238. | 排版问题 / 字溢出 / 撑出框 | 先看 HTML 参考图是否也溢出;若 HTML 正常、PPT 异常,按 `references/lessons-learned.md` 排查 |
  239. | 装饰显示成方块 | 看 compare 图判断是几何、画面捕获还是渲染器差异,查 `lessons-learned.md` 的 OOXML 边界表 |
  240. | 字体不对(PowerPoint 里看) | 查 `lessons-learned.md` "已知 regression checkpoint" 的 GF 字体名归一 / weight 槽分配两条;撞到了 HTML 端绕开(换字体名 / 调权重)+ 告知作者提 issue |
  241. | 字体不对(WPS 里看) | 99% 是 WPS 不读裸 TTF 嵌入字体。问用户是否同意装到用户字体目录后用 `--install-user-fonts` 重转 |
  242. | 中文显示方框 □□□ | 检查 OOXML rPr 的 `<a:ea>` 是否走了 CJK 字体 |
  243. | 居中文字位置偏下 / 偏出容器 | 查 `lessons-learned.md` "已知 regression checkpoint" 的 `flex + align-items:center` 条目;撞到了 HTML 端绕开(拆容器 / 改对齐)+ 告知作者提 issue |
  244. ## 不要
  245. - 不向用户解释完整管线(除非问),只报告转换结果与告警
  246. - 不在未看 audit compare 图前就归因
  247. - 不承诺 1:1 视觉还原 —— OOXML 表达力有限
  248. ## 排查路径
  249. **先判档位**:80% 的 finding 不是档位内 bug,是档位选错了。看 `<out>_preflight.json` 或 `<out>_measurements.json` 里这个元素走了 text / shape / deco_snapshot / svg 哪条路径,对照症状:
  250. | 症状 | 大概率原因 |
  251. |---|---|
  252. | 走 `deco_snapshot` 但视觉缺装饰 | 截图前的 hide JS 漏掉了什么;或 deco 区域比预期小 |
  253. | 走 `text` 但样式没对上(颜色 / 字号 / 行距) | measure 抓 style 字段不全 / assemble 翻译漏字段 |
  254. | 走 `shape` 但圆角 / border 不对 | border-radius 数值或 `_round_kind` 阈值 |
  255. | 视觉效果(gradient / shadow / filter)完全丢 | **该走 deco_snapshot 但没走** — `hasComplexDecoration` 漏触发,加一行 |
  256. | 文字消失 | 走了截图档但没发对应 text 记录;或 hide JS 把不该 hide 的也 hide 了 |
  257. 然后再走通常流程:
  258. 1. 看 Stage 5a 自检报告:哪几页被告警
  259. 2. 看 Stage 5b audit 结果:按 `audit.mode` 获取 findings 或人工反馈;只有用户反馈 / 告警对应页需要人工复核时,才用 Read 看那一页 compare 图
  260. 3. 搜 `references/lessons-learned.md` 已知症状(HTML 反模式 / OOXML 边界)
  261. 4. HTML 正常、PPT 异常且不符合已知边界 → 看是不是 skill 抽象不到位(按"看似 skill 内 bug 怎么处理"流程:HTML workaround 修当前 deck + 告知用户提 issue)
  262. ## 引用
  263. - 五步反假设流水线 + 每步反假设规则 + 退出断言 + 新模板 checklist → [`references/methodology.md`](./references/methodology.md)(作者扩展 skill 时读,agent 调用不必读)
  264. - CSS 覆盖范围(四档详表)+ `hasComplexDecoration` 完整触发清单 + 加新支持的标准做法 → [`references/supported-css.md`](./references/supported-css.md)(agent 想理解某 CSS 走哪档时读,作者扩展必读)
  265. - 历史踩坑修复 + HTML 反模式 + OOXML 边界 → `references/lessons-learned.md`(agent 排查必读)。本地工作副本(gitignored,首次 convert 自动从 `lessons-learned.md.example` seed),自由加 / 改 / 整理;想上游某条 → 作者手动复制回 `.example` 再 commit
README.md · README · 242 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <h1 align="center"><b>HTML-TO-PPTX</b></h1>
  2. <p align="center">
  3. <a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white" alt="Python"></a>
  4. <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
  5. <a href="#manual-usage-without-claude-code"><img src="https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey" alt="Platform"></a>
  6. <a href="SKILL.md"><img src="https://img.shields.io/badge/Claude%20Code-skill-D97757" alt="Claude Code skill"></a>
  7. </p>
  8. <p align="center"><sub>📖 <b>English</b> | <a href="README.zh-CN.md">中文</a></sub></p>
  9. Convert HTML slide decks into editable `.pptx`: text stays as native PowerPoint textboxes, fonts are subset on demand, complex CSS decorations fall back to local snapshots, and HTML/PPT side-by-side audit material is generated for review.
  10. <table align="center">
  11. <tr>
  12. <td width="50%"><img src="assets/compare/yanshi2_html_grid.png" alt="Original HTML rendering"></td>
  13. <td width="50%"><img src="assets/compare/yanshi2_ours_grid.png" alt="html-to-pptx output rendered in PowerPoint"></td>
  14. </tr>
  15. <tr>
  16. <td align="center"><sub><b>Original HTML</b></sub></td>
  17. <td align="center"><sub><b>html-to-pptx output, opened in PowerPoint</b></sub></td>
  18. </tr>
  19. </table>
  20. <p align="center"><sub>Text stays as editable vectors; complex decorations are rasterized locally.</sub></p>
  21. ## Why this exists
  22. HTML is a great medium for slide decks — layout, typography, animation, and complex visuals are all more flexible than in PowerPoint. But delivery often requires `.pptx`, and most "HTML → PPT" tools flatten each page into a single image, leaving text uneditable, unsearchable, and pixelated when zoomed.
  23. html-to-pptx avoids the "whole-page screenshot" route. It decomposes HTML into objects PowerPoint understands: text becomes editable textboxes; simple geometry becomes native shapes / lines; effects PPT can't express natively (gradients, shadows, filters, blend modes) are snapshotted locally and placed as a decoration layer behind the vector text.
  24. The result: the output stays close to the HTML source while remaining searchable, editable, and rescalable in PowerPoint / WPS — not a stack of immutable images.
  25. ## Gets better with use
  26. Each install keeps a private `references/lessons-learned.md` — seeded once from the committed template, then gitignored. When the audit loop turns up a generalizable HTML anti-pattern or OOXML boundary, the fix recipe gets appended there. Every subsequent convert re-reads the file, so decks sharing traits with ones you've already audited tend to land cleaner on the first pass.
  27. The local copy is never overwritten by upstream — `git pull` updates the template, not your accumulated notes.
  28. ## What it handles
  29. Supports single-file HTML decks from [beautiful-html-templates](https://github.com/zarazhangrui/beautiful-html-templates) / [guizang-ppt-skill](https://github.com/op7418/guizang-ppt-skill) / Reveal.js / hand-written decks / browser fullscreen pages, with automatic slide detection.
  30. CSS → PPT routing:
  31. | HTML element / CSS | What it becomes in PPT |
  32. |---|---|
  33. | Text, rich text, color, size, tracking, line-height, alignment | Editable textboxes — searchable and scalable |
  34. | Background color, border, border-radius, lines | Native OOXML geometry |
  35. | `gradient`, `box-shadow`, `filter`, `backdrop-filter`, `mix-blend-mode`, complex transforms | Local snapshot underlay; text still drawn on top as vector |
  36. | SVG, images, canvas | Embedded directly |
  37. | Google Fonts | Subset by characters actually used; CJK content auto-seeds Noto Sans SC / Noto Serif SC |
  38. For the full CSS coverage matrix, see [references/supported-css.md](references/supported-css.md).
  39. ## Quick start (Claude Code)
  40. ### Install
  41. In a Claude Code session, just hand Claude the repo URL:
  42. ```text
  43. Install this skill for me: https://github.com/Hasasasa/claude-skill-html-to-pptx
  44. ```
  45. Claude will `git clone` it into the right skills directory for your platform (macOS / Linux: `~/.claude/skills/`; Windows: `%USERPROFILE%\.claude\skills\`) and walk you through installing Python 3.10+, Playwright, and dependencies. System-level steps will still ask for your confirmation.
  46. ### Use
  47. After install, ask in plain language:
  48. ```text
  49. Convert D:\path\to\deck.html to pptx
  50. ```
  51. Full skill invocation rules, audit mode, and fix discipline are in [SKILL.md](SKILL.md).
  52. ## Manual usage (without Claude Code)
  53. If you're not using Claude Code, clone the repo and run the CLI directly.
  54. ### Install
  55. Requires Python 3.10+ and pip.
  56. ```bash
  57. git clone https://github.com/Hasasasa/claude-skill-html-to-pptx.git
  58. cd claude-skill-html-to-pptx
  59. pip install -r requirements.txt
  60. python -m playwright install chromium
  61. ```
  62. The visual audit step renders `.pptx` to PNG. Either of the following works:
  63. - Windows + Office
  64. - LibreOffice
  65. `requirements.txt` already includes `pywin32` (Windows-only) and `pdf2image`. For the LibreOffice route, you also need LibreOffice installed on the system; on Windows, `pdf2image` typically needs Poppler too. The `.pptx` itself still generates without a renderer — only the HTML/PPT side-by-side audit images are skipped.
  66. ### Run
  67. ```bash
  68. python convert.py path/to/deck.html
  69. ```
  70. Output goes to `path/to/deck.pptx` next to the input. On first run, a working copy at `path/to/deck.audited.html` is created automatically; all subsequent audit fixes modify this copy, leaving the original HTML untouched.
  71. Common flags:
  72. | Flag | What it does |
  73. |---|---|
  74. | `--out <path>` | Custom output `.pptx` path |
  75. | `--keep-screenshots` | Keep per-slide HTML reference screenshots and measurement files |
  76. | `--install-user-fonts` | Install non-CJK fonts into the user font directory so WPS / PowerPoint COM can render them |
  77. | `--no-embed-fonts` | Skip font embedding — smaller file but may fall back to system fonts on other machines |
  78. | `--no-preflight` | Skip the Stage 1 risk pre-scan |
  79. | `--no-verify` | Skip the Stage 5a structural self-check |
  80. | `--no-visual-audit` | Skip the Stage 5b visual audit material generation |
  81. | `--only-slides 2,7,12` | Re-run only the listed slides (incremental mode for audit iteration) |
  82. | `--cleanup` | Clean up audit / measurement / preflight intermediate artifacts |
  83. ### Tests
  84. Regression tests cover OOXML invariants (assemble), font-resolver caching semantics, and browser-based measure/discovery checkpoints (auto-skipped if Playwright/Chromium is unavailable):
  85. ```bash
  86. python -m pytest tests -q
  87. ```
  88. ## More demos
  89. Each pair: HTML rendering on the left, html-to-pptx output (rendered in PowerPoint) on the right.
  90. ### Signal
  91. <table align="center">
  92. <tr>
  93. <td width="50%"><img src="assets/compare/yanshi1_html_grid.png" alt="Signal HTML rendering"></td>
  94. <td width="50%"><img src="assets/compare/yanshi1_ours_grid.png" alt="Signal PPT output"></td>
  95. </tr>
  96. <tr>
  97. <td align="center"><sub><b>HTML</b></sub></td>
  98. <td align="center"><sub><b>html-to-pptx output</b></sub></td>
  99. </tr>
  100. </table>
  101. ### Market Outlook
  102. <table align="center">
  103. <tr>
  104. <td width="50%"><img src="assets/compare/blue_html_grid.png" alt="Market Outlook HTML rendering"></td>
  105. <td width="50%"><img src="assets/compare/blue_ours_grid.png" alt="Market Outlook PPT output"></td>
  106. </tr>
  107. <tr>
  108. <td align="center"><sub><b>HTML</b></sub></td>
  109. <td align="center"><sub><b>html-to-pptx output</b></sub></td>
  110. </tr>
  111. </table>
  112. ### OpenClaw — Human-AI Collaboration Framework
  113. <table align="center">
  114. <tr>
  115. <td width="50%"><img src="assets/compare/openclaw_html_grid.png" alt="OpenClaw HTML rendering"></td>
  116. <td width="50%"><img src="assets/compare/openclaw_ours_grid.png" alt="OpenClaw PPT output"></td>
  117. </tr>
  118. <tr>
  119. <td align="center"><sub><b>HTML</b></sub></td>
  120. <td align="center"><sub><b>html-to-pptx output</b></sub></td>
  121. </tr>
  122. </table>
  123. ### 8-Bit Orbit
  124. <table align="center">
  125. <tr>
  126. <td width="50%"><img src="assets/compare/8bit_html_grid.png" alt="8-Bit Orbit HTML rendering"></td>
  127. <td width="50%"><img src="assets/compare/8bit_ours_grid.png" alt="8-Bit Orbit PPT output"></td>
  128. </tr>
  129. <tr>
  130. <td align="center"><sub><b>HTML</b></sub></td>
  131. <td align="center"><sub><b>html-to-pptx output</b></sub></td>
  132. </tr>
  133. </table>
  134. ### Apex Group (Bold Poster)
  135. <table align="center">
  136. <tr>
  137. <td width="50%"><img src="assets/compare/bold_html_grid.png" alt="Bold Poster HTML rendering"></td>
  138. <td width="50%"><img src="assets/compare/bold_ours_grid.png" alt="Bold Poster PPT output"></td>
  139. </tr>
  140. <tr>
  141. <td align="center"><sub><b>HTML</b></sub></td>
  142. <td align="center"><sub><b>html-to-pptx output</b></sub></td>
  143. </tr>
  144. </table>
  145. ### Broadside
  146. <table align="center">
  147. <tr>
  148. <td width="50%"><img src="assets/compare/broadside_html_grid.png" alt="Broadside HTML rendering"></td>
  149. <td width="50%"><img src="assets/compare/broadside_ours_grid.png" alt="Broadside PPT output"></td>
  150. </tr>
  151. <tr>
  152. <td align="center"><sub><b>HTML</b></sub></td>
  153. <td align="center"><sub><b>html-to-pptx output</b></sub></td>
  154. </tr>
  155. </table>
  156. ## Pipeline
  157. ```text
  158. [1 preflight] -> [2 measure] -> [3 assemble] -> [4 embed fonts] -> [5a self check] -> [5b visual audit]
  159. preflight.py measure.py assemble.py embed_fonts.py self_check.py visual_audit.py
  160. ```
  161. - `preflight`: scan for high-risk HTML/CSS patterns.
  162. - `measure`: probe the DOM with Playwright, extracting text, shape, media, and decoration records.
  163. - `assemble`: write OOXML — textbox / shape / media / snapshot.
  164. - `embed_fonts`: subset and embed fonts by characters actually used.
  165. - `self_check`: scan PPTX for structural risks and call the renderer to export per-slide PNGs.
  166. - `visual_audit`: generate HTML/PPT side-by-side images, contact sheet, audit index, and the review prompt.
  167. ## Design principles
  168. | Principle | What it means |
  169. |---|---|
  170. | Vector-first | Text and simple geometry stay as native PPT objects — editable, searchable, scalable |
  171. | Local fallback | Only complex decorations go through the snapshot channel — no whole-page rasterization |
  172. | Portable fonts | Google Fonts auto-resolved and subset-embedded to reduce cross-machine drift |
  173. | Auditable | Per-slide HTML/PPT comparison material lets visual issues be located and iterated |
  174. | Source-preserving | A `.audited.html` working copy is created automatically; the original HTML is never modified |
  175. ## Further reading
  176. - [SKILL.md](SKILL.md): Claude Code skill invocation rules, audit mode, fix discipline.
  177. - [references/methodology.md](references/methodology.md): the five-step pipeline and anti-assumption checklist.
  178. - [references/supported-css.md](references/supported-css.md): CSS-to-PPT routing coverage matrix.
  179. - [references/lessons-learned.md.example](references/lessons-learned.md.example): historical issues, HTML anti-patterns, and OOXML boundaries.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.