Markdown 幻灯片

md-slides
分类Office
作者Alireza Rezvani
许可MIT
评分4.20/5
使用10.5K

md-slides — Markdown 幻灯片 → 单文件 HTML 演示文稿

幻灯片转换工具。读取 Markdown 幻灯片（由水平线或 H1 分隔，含可选演讲者备注），生成可在任何浏览器中运行的单文件 HTML 演示文稿，支持键盘导航、演讲者模式和打印为 PDF。

三个标准库工具组成流水线：

code
slide_splitter.py  →  presenter_notes_parser.py  →  deck_html_renderer.py
   (md → 有标题的      (提取 <!-- notes:         (幻灯片 + 设计系统
    有序幻灯片)         --> 块并关联至            token → 带键盘导航的
                        每张幻灯片)              单文件 HTML)

调用时机

| 现象 | 操作 |
|---|---|
| markdown-html-orchestrator 将输入路由为 SLIDES | 调用此技能 |
| 用户直接运行 /cs:md-slides <path>.md | 调用此技能 |
| 输入包含 3 条以上 --- 水平线 或 5 个以上正文较短的 H1 标题 | 调用此技能 |
| 输入为长篇规范文档 | 路由至 md-document |
| 输入为代码审查 | 路由至 md-review |
| 输入没有明确的幻灯片边界 | 拒绝，路由至 md-document |
| 输入仅会产生 1 张幻灯片 | 拒绝（这属于海报） |

流水线

bash
# 1. 根据 --- 或 H1 分割幻灯片（默认自动检测）
python3 markdown-html/skills/md-slides/scripts/slide_splitter.py \
    --input <path>.md --output /tmp/slides.json

2. 从每张幻灯片中提取 <!-- notes: ... --> 块

python3 markdown-html/skills/md-slides/scripts/presenter_notes_parser.py \
    --slides /tmp/slides.json --output /tmp/deck.json

3. 渲染单文件 HTML 幻灯片

python3 markdown-html/skills/md-slides/scripts/deck_html_renderer.py \
    --slides /tmp/deck.json --title "My Talk" --output deck.html

HTML 包含的内容

  • 所有幻灯片均作为 <section class="slide"> — 由 JS 控制每次仅显示一张
  • 键盘导航 — → / Space / PgDn 下一张；← / PgUp 上一张；Home/End 跳转；P 进入演讲者模式；Esc 退出演讲者模式
  • URL 哈希深层链接 — #3 跳转至第 3 张幻灯片；浏览器前进/后退可切换幻灯片；分享 deck.html#5 可直接引导至第 5 张
  • 进度条 — 顶部 3px 进度条，显示当前在幻灯片集中的位置
  • 幻灯片计数器 — 右下角显示（如 "3 / 12"）
  • 演讲者模式 (P 键) — 分屏显示：左侧为当前幻灯片（60% 宽度），右侧面板包含时钟 + 演讲者备注 + 下一张预览
  • 打印样式表
  • Cmd+P — 生成每页一张幻灯片的 PDF
  • 支持 @media (prefers-reduced-motion: reduce)
  • 包含 12 个来自 design-system 的品牌 CSS 自定义属性；design_style 影响布局密度
  • 复用 md-document 的 markdown 解析器 — 幻灯片正文在段落/列表/代码/表格/ callout 的处理上保持一致

硬性规则

1. 拒绝无明确幻灯片边界的输入。 自动模式需要 $\ge 3$ 条水平线（HR）或 $\ge 5$ 个 H1 标题。否则退出码 6 — 路由至 md-document。
2. 拒绝单页幻灯片。 那是海报而非演示文稿。退出码 5。
3. 拒绝少于 100 行的输入。 与所有转换器一致的 Shihipar 阈值。
4. 拒绝未经过引导（onboarding）的输入。 与所有转换器一致的准入机制。
5. --strict-notes 拒绝备注覆盖率 $< 50\%$ 的输入。 大部分幻灯片没有备注的文稿不适合演讲者模式。退出码 7。
6. 对超过 40 行源码的幻灯片发出软警告。 旨在控制信噪比；仍会渲染但会显示行数。
7. 单文件输出。 所有 CSS + JS 均内联。唯一外部引用为 Google Fonts CSS。Prism.js 通过 --syntax 可选开启。
8. 无 JS 框架运行时。 仅使用原生 JS + 键盘事件处理器，不使用 React/Vue/Svelte。

强制质询库（Matt Pocock 式严苛审查）

1. 这真的是一套幻灯片，还是一个长文档？ 建议：如果无法划定明确的幻灯片边界，则不是幻灯片。参考：Tufte *Cognitive Style of PowerPoint*。
2. 使用 HR (---) 还是 H1 作为边界？ 建议：常规幻灯片用 HR；大纲驱动的幻灯片用 H1。参考：Marp / reveal.js / pandoc 的共识。
3. 是用于现场演示还是分发自读？ 建议：现场 $\rightarrow$ 需要演讲者备注；自读 $\rightarrow$ 备注可选。参考：Weinschenk *100 Things Every Presenter Needs to Know*。
4. 是否有单页源码超过 40 行的幻灯片？ 建议：将其拆分。参考：NN/g — 观众注意力在超过 $\sim 6$ 个要点 / 200 字后会下降。
5. 是否需要 --syntax？ 建议：仅在包含大量代码块的幻灯片中使用。默认关闭。参考：单文件可分享性原则。

区别于

  • md-document — 后者是单一连续文档，而这是 N 张离散的幻灯片。
  • md-review — 后者渲染 diff 块 + 注释，而这是渲染正文幻灯片。
  • marketing/landing/ — 后者是落地页，而非幻灯片。
  • Keynote / PowerPoint — 那些是图形设计工具，而这是用于在浏览器中投影的 Markdown 编写文稿。

输出产物

{default_output_dir}/deck-{slug}.html（路径由编排器的 output_path_resolver.py 解析；冲突时默认添加后缀 -2, -3, …）。

参考资料

  • Shihipar — *Claude Code HTML output* (Medium, 2026), Tier 3 场景 "Slide Decks"
  • Reynolds — *Presentation Zen*（极简主义原则）
  • Atkinson — *Beyond Bullet Points*（针对过度依赖要点的失败模式）
  • Tufte — *The Cognitive Style of PowerPoint*（批判性视角）
  • reveal.js / Big / Marp — Markdown 转幻灯片的通用约定
  • 详见 references/ 获取完整引用 (presentation_ux, keyboard_nav_patterns, single_file_deck_conventions)