HTML幻灯片生成器 (ym-html-deck-builder)

把一份 Markdown 大纲（或对话里给的主题）渲染成单文件、可全屏演示的 HTML 幻灯片。不联网、不依赖任何第三方库，双击即可在浏览器全屏放映，键盘翻页并带底部进度条与页码。

何时使用

• 用户说「做个 PPT」「生成幻灯片」「HTML 演示文稿」「翻页课件」时
• 用户手里有一份大纲（标题 + 要点），但排版丑、不会做动画、不想装 Office 时
• 用户需要把一次分享/宣讲快速变成可放映文件，且要求零依赖、可离线打开时

运行前提

• 环境：Python 3.7+，仅用标准库（argparse / html / os / sys），无需联网、无需 pip 安装
• 输入文件：一份 Markdown 大纲；若用户只给主题没给大纲，先按 templates/deck-outline.md 帮用户整理成大纲再渲染
• 输出文件：当前目录下生成 deck.html，同名会覆盖
• 翻页/全屏依赖浏览器，不依赖本地服务器；直接双击打开即可

输入契约

标题层级直接决定页面样式，对应关系如下：

• # 一级标题 → 封面页 / 结尾页，居中大标题，适合放主题与致谢
• ## 二级标题 → 章节页，居中强调，用于把演示分成几大块
• ### 三级及以下 → 内容页，左对齐，标题下方是要点或段落

缺失处理：

• 缺大纲文件 → 用 templates/deck-outline.md 的模板请用户补，或把对话里的主题先落成大纲（例如用户说「讲讲我们上季度的增长」，就先拟 # 上季度增长复盘 + 几页 ### 要点）
• 大纲第一页非 # 开头 → 自动作为封面页处理，标题取该段文字，避免首屏空白
• 大纲为空 → 脚本退出并报错「大纲为空，未解析到任何页」，不生成空文件，防止用户打开一个只有进度条的空页面
• 用户只给主题不给要点 → 不要替用户编造事实性内容，先追问关键结论再生成

执行步骤

1. 整理大纲 — 让用户给出主题或现有要点，按 templates/deck-outline.md 写成 # 封面页 / ## 章节页 / ### 内容页 / # 结尾页 结构，要点用 - 列。

2. 渲染 — 在技能目录下执行：

   python scripts/build_deck.py outline.md --title "季度复盘" --theme dark
   

   仅要浅色主题可省略 --theme；想限制页数加 --limit 20。脚本读取大纲后写出 deck.html 并打印「已生成 deck.html，共 N 页」。

3. 打开检查 — 双击 deck.html 用浏览器打开，按下面的验收清单逐项验证键盘与进度条。

4. 交付 — 把 deck.html 交给用户；可一并说明 ←/→、空格、PgUp/PgDn、Home/End、Esc 目录、F 全屏等按键。

大纲编写示例

下面是一份可直接渲染的 5 页大纲（保存为 outline.md，UTF-8）：

# 上季度增长复盘

## 章节：做了什么

### 关键动作
- 上线会员体系，新增付费用户 1.2 万
- 优化首屏，耗时下降 40%

### 结果
- 月活环比增长 18%
- 留存提升 5 个百分点

## 章节：下一步

### 重点
- 推进多端组件统一
- 建立自动化回归基线

# 谢谢 · 欢迎提问

渲染命令：

python scripts/build_deck.py outline.md --title "上季度增长复盘" --theme dark

生成后首页为封面、两个 ## 为章节页、### 为内容页、末页为结尾页。

输出格式

单个自包含 HTML 文件 deck.html：

• 每页一个 section 元素（class 为 slide），通过 active 类切换显隐
• 首页（#）为封面样式（居中大标题），## 为章节页样式（居中强调标题），其余为内容页（标题 + 要点/段落）
• 底部固定进度条（宽度随页推进）+ 右下角页码「当前 / 总页」
• 按 Esc 弹出目录浮层，列出所有页标题，点击跳转到对应页
• 内置 light / dark 两套主题，由 html 元素的 data-theme 属性切换

能力边界

• 不做动画与转场特效（切页为瞬时显隐，无淡入淡出）
• 不做多人协作编辑、不导出 .pptx / PDF（后续版本考虑）
• 不支持图片嵌入（后续版本考虑）；要点仅限文字
• 不联网、不读取大纲以外的本地文件、不上传任何数据
• 不负责内容正确性：脚本只做排版渲染，结论是否准确由用户提供，技能不替用户编造数据
• 不生成目录缩略图、不导出图片序列；需要静态图先截图

与其它幻灯片技能的区别

• 本技能面向「不会排版、要快速放映」的人，输入是自由大纲，输出是纯放映文件；不强制金字塔结构。
• ym-report-slide-gen 面向「向领导汇报」，强制结论先行 + 数据表格 + 页数限时，输入是四类素材而非自由大纲。
• ym-training-courseware 面向内训讲师，输出带左侧章节导航与课堂提问页，结构由课程设计表驱动。

常见坑

0. 中文显示成方块或宋体 — 现象：deck.html 在个别机器上中文变方块、或整体掉成衬线宋体。原因：生成机与演示机字体不一致，CSS 只写单一字体名时缺失即回退到浏览器默认。规避：模板已内置回退栈 Microsoft YaHei → PingFang SC → Hiragino Sans GB → Heiti SC → WenQuanYi Micro Hei → sans-serif（Windows / macOS / Linux 各有命中），最后必须以 sans-serif 收尾；缺字体的表现是样式突然变宋体而非报错，演示机优先检查是否装了「微软雅黑」。

1. Windows 下读文件乱码（GBK） — 现象：中文大纲渲染成乱码或报 UnicodeDecodeError。原因：Python 在 Windows 默认用系统编码（常是 GBK）读文本。规避：脚本一律 open(path, encoding="utf-8") 读、以 utf-8 写，用户大纲也必须保存为 UTF-8；在编辑器里存盘时确认编码为 UTF-8。

2. 全屏按键 F 无效 — 现象：按 F 没进入全屏。原因：浏览器全屏 API（requestFullscreen）只在 https:// 或 localhost 下允许，直接双击用 file:// 打开会被拦截。规避：脚本已做降级——捕获异常后仅在控制台提示，不影响翻页；用户可用浏览器自带全屏（F11 / 右上角菜单）代替。

3. 中文字体回退缺失导致方框 — 现象：某些系统字体栈只写 sans-serif，中文回退到豆腐块。原因：未列出中文优先字体。规避：font-family 写全栈——"Microsoft YaHei","PingFang SC","Hiragino Sans GB","Heiti SC","WenQuanYi Micro Hei",sans-serif，覆盖 Windows / macOS / Linux。

4. 打印或导出 PDF 被分页截断 — 现象：浏览器打印时一页 HTML 被拆成多张纸。原因：幻灯片用绝对定位铺满视口，打印分页会切断。规避：建议演示用放映而非打印；若必须打印，先用浏览器的「打印 → 背景图形」并逐页 Esc 定位后再打印，或后续用专用导出脚本。

5. 标题级别误用导致样式不对 — 现象：章节页没居中强调、封面不像封面。原因：把章节页写成 #、内容页写成 ##。规避：严格按 # 封面 / ## 章节 / ### 内容分层；脚本按 # 个数判定样式。

6. 要点过长挤出版面 — 现象：一页要点超出屏幕被截断。原因：单页塞了过多文字。规避：每页要点控制在 5 条内、每条不超过一行半；过长内容拆成多页或下沉到段落。

验收用例

• 正常：给 5 页大纲（含 # 封面页、## 章节页、若干 ### 内容页、# 结尾页）→ ←/→、空格、PgUp/PgDn 翻页全部有效；进度条随页推进；Home/End 跳首末页；Esc 目录跳转正确；页码实时更新。
• 边界 1：浅色与深色各生成一次，确认 data-theme 切换、配色变量生效。
• 边界 2：--limit 设小于实际页数 → 控制台提示超限但不截断，文件仍可放映。
• 失败：空大纲文件 → 脚本退出码非 0，报「大纲为空」，不产出 deck.html。

目录说明

• scripts/build_deck.py — 主脚本，读大纲渲染成单文件 deck.html
• references/html-patterns.md — 翻页 JS 实现模式（键盘事件表、进度条计算、目录浮层）与两套主题 CSS 变量约定
• templates/deck-outline.md — 大纲文件模板（封面页 / 章节页 / 内容页 / 结尾页写法说明）