当课件住进了博客——Slide Maker Skill 诞生记

最近在做 LoRA 课件时，我盯着 Marp 导出的 PDF 想——这玩意儿能不能直接挂到博客上？

不是导出个文件扔网盘那种。我想要的是：课件有自己的 URL，有缩略图预览，有分类标签，和博文一样被管理，但演示时是全屏的交互体验。

两个多小时后，这件事做完了。

为什么不用 PowerPoint

LoRA 课件有三样东西让传统 PPT 痛苦：

• 大量 Python 代码 — PPT 里贴代码块没有语法高亮，字号还得手动调
• 数学公式 — W₀ + (α/r)·BA，在 PPT 里插公式编辑器是折磨
• 版本控制 — .pptx 是二进制文件，改一个字 git diff 看不出来

reveal.js 全部解决：代码用 highlight.js 渲染，公式用 KaTeX，内容就是 HTML——纯文本，git diff 友好。

架构：一个问题引出三层设计

最开始的问题很简单：slides 放哪？

但这里有个坑：Zola 的 content/ 和 static/ 会在 build 时合并到同一个 public/ 目录。如果 reveal.js 的 HTML 叫 index.html，会和 Zola 生成的页面打架。

小龙虾一句话解决：叫 reveal.html 就行。

最终三层架构：

static/slides/{slug}/reveal.html    → 全屏演示（reveal.js）
static/slides/{slug}/thumbnail.png  → 首页截图（Playwright 自动生成）
content/slides/{slug}.md            → Zola 介绍页（标题 + 描述 + 缩略图）

三者各司其职，路径零冲突。zola build 后：

• /slides/lora-lesson-1/ → 介绍页（Zola 渲染）
• /slides/lora-lesson-1/reveal.html → 全屏演示（静态文件直出）

从手工到 Skill：让流程可复用

第一套 slides 是手写的——把 Marp 格式的 slides.md 逐页转成 reveal.js 的 <section> 标签。深色科技风主题、代码逐行高亮、fragment 逐条揭示、章节渐变背景，22 页 slides 做下来效果不错：

但"做下来"和"能再做"是两回事。

如果以后要做 Lesson 2、做会议演讲、做技术分享，每次都从零手写 HTML？不合理。于是封装成了 slide-maker Skill。

Skill 做的事很简单——五步流水线：

1. 检查模板 — 确认 Zola 的 slides 模板存在
2. 收集输入 — 标题、slug、内容来源（Marp / 大纲 / 自然语言描述）
3. 生成 reveal.html — CDN 引用、深色主题、KaTeX + highlight.js
4. 生成 content md — Zola frontmatter + 介绍页
5. Playwright 截图 — 自动截取首页作为缩略图

下次我只需要说"把 Lesson 2 也做成课件"，Skill 自动加载，直接干活。

小龙虾的 Review

小龙虾给了三条建议，三条都落地了：

P1: SKILL.md 提到了模板但没说怎么创建，执行时可能报错 → 加了 Step 0 前置检查

P2: [extra] 里的 slug 是冗余的，不如直接用 slides_url → 语义更清晰，模板里 {{ page.extra.slides_url }} 一目了然

P3: 说了"介绍页放截图"但没定义截图怎么来 → 加了 Playwright CLI 自动截图步骤

最终评分 9.0/10。

试试看

现在 polly.wang/slides/ 已经上线，第一套课件是 LoRA 训练原理——22 页 slides，从显存账到手撕代码到 SVD 可视化。

鼠标悬停缩略图会有"点击全屏演示"的遮罩提示。进入全屏后：

• → / 空格 下一步（含逐条揭示动画）
• ↓ 进入章节子 slide
• Esc 全局缩略图
• S 演讲者笔记

课件的内容可以随时修改——它就是一个 HTML 文件，改完刷新即生效。

一个意外的发现

做完之后回头看，最让我满意的不是 reveal.js 本身——那只是个框架。让我满意的是课件成了博客的一等公民。

它有自己的列表页，有缩略图，有分类标签，和博文共享同一套 taxonomy。当 slides 数量多起来后，/slides/ 页面会像 /blog/ 一样成为一个内容入口。

PPT 文件是孤岛。而住进博客的课件，是活的。