从 Markdown 到幻灯片——用纯文本做演示文稿

1. 幻灯片文件的问题

传统幻灯片文件把内容和版式混在一个二进制包里，任何结构性调整都是手工活：调整三个章节的顺序，就意味着拖拽页面、重排每个标题。幻灯片工具的版本历史从薄弱到没有，评审一份片子意味着打开那个应用。

文本驱动的幻灯片把模型倒了过来。演示文稿是一个 Markdown 文件，页面由分隔符（Marp 的 ---）或标题切分。文件可以干净地 diff、干净地版本化，通过一个应用统一主题的工具渲染。你写论证，工具管排版。

这是 docs-as-code 的思路套在另一种产物上——和文档站一样，源文件才是资产，导出不是。

2. Marp——为幻灯片而生的 Markdown

Marp（Markdown Presentation Ecosystem）就是为这套工作流而造。一个 --- 分隔符开新页；每页的 front matter 控制版式（paginate: true、双栏指令）；支持图片，数学公式经 LaTeX 记号渲染；Marp CLI 导出 PDF、PowerPoint（.pptx）和 HTML——HTML 版在任何浏览器里实时渲染，顺手兼任演示视图。

最小的一份片子：

---
marp: true
theme: default
---

# 论点

一页一个想法，就像一个文件一件事。

---

## 证据

- 幻灯片文本可以在 pull request 里评审
- 主题是一行配置

Marp 文档覆盖了指令体系；生态里还有带实时预览的 VS Code 扩展——改文本，看页面。截至 2026 年，它仍然是门槛最低的入口。下面五个小节，把做出第一份真实片子之前值得弄懂的部分走一遍。

2.1 指令体系

一份 Marp 片子的配置方式和构建任务一样：一块键值对的 front matter，作用于全片。marp: true 开启幻灯片渲染；theme: 在内置的 default、gaia、uncover 三个主题里挑一个；paginate: true 打开页码；size: 16:9 选画布，另一个预设是 4:3。真正改变写作方式的是 headingDivider: 2——它在每个二级标题处自动分页，文档标题结构干净的话，一个 --- 都不用写就成了片子。

指令也可以按页生效，写成 HTML 注释。<!-- paginate: skip --> 让标题页不显示页码；<!-- _class: lead --> 给当前页套用居中的标题页版式，下划线的意思是只作用于这一页。版式决策因此变成评审者可以逐行评论的 diff 行——这正是幻灯片文件从来给不了的属性。

2.2 图片与背景图

内联图片用普通 Markdown 语法，写在替代文本里的 bg 修饰符让它升级为背景：bg 单独用，图片铺满整页；bg right:50% 把画布右半边交给图片，左半边留给文字；w:480px、fit 这类尺寸修饰符控制缩放。两张背景图并排写，画布会自动切成两列——技术片子里最常见的那种页面，左边文字右边一张图，一行标记就完成了。

这个能力覆盖了质疑者口中「艺术指导缺口」的相当一部分。可预测的五五开当然不是像素级排版，但「文字加一张图」这类页面它能确定性地解决；真需要图片占 63% 宽、文字环绕其侧的设计，那一页还是该交给设计工具。知道一行方案的边界在哪，就是这个工作流需要的判断力的大半。

2.3 长在文件里的演讲者备注

任何不是指令的 HTML 注释都会成为演讲者备注。<!-- 这个数字未经审计——被问到就直说 --> 停在它注释的那一页下面，像片子的其余部分一样可以 diff、可以评审。备注不会和页面失同步，因为它就长在页面之间；CLI 的 HTML 导出自带浏览器演示视图，显示当前页、下一页和这些备注。

这最后一个属性对一类内容尤其重要：那些属于现场、但不该上屏的上下文——限定语、出处、不能念出声的数字。评论把这些上下文钉在确切的那一页上，单独维护的讲稿文档从来做不到这一点。

2.4 双栏与分步显示

这里有两个诚实的局限，都有已知的绕法。Marp 没有一等的双栏指令：标准做法是在片子的 style front matter 里写几行 CSS 再加两个包裹 div，HTML 需经 CLI 的 --html 开关启用——不过上一小节的五五开背景图经常用纯 Markdown 就做出同样的版式。Marp 也没有 fragments（逐条点出的分步显示），而这个缺席是设计决策，不是疏漏。

分步的务实绕法是复制：复制这一页，删掉还没讲到的行，让演讲在几个几乎相同的页面之间翻页。它在编辑器里笨拙，在现场完全够用，还有个副产品——PDF 讲义里每一步同时可见，因为「步骤」只是相邻的几页。当点击动画真的承担论证功能时，就是下面开发者工具接管的边界。

2.5 VS Code 实时预览环

Marp 的 VS Code 扩展把「写」和「看」之间的环闭合了。预览窗格在文本旁边实时渲染片子，指令写错会以编辑器警告的形式浮出来而不是炸在导出里，命令面板可以把同一份文件导出为 PDF、PowerPoint 或 HTML。这个工作流就是文档工程师已经跑熟的那一套——起草、瞥一眼、收紧——套在了幻灯片上。

3. Pandoc——幻灯片只是又一种导出

如果你已经在跑单一源工作流——简历、文档、报告——Pandoc 把幻灯片当作又一个构建目标：pandoc talk.md -o talk.pptx，或经 Beamer 模板出 PDF。标题层级映射到页面和子页面边界。

这个映射值得展开，因为它就是全部心智模型。Pandoc 会推导一个幻灯片层级——通常是二级——该层级的每个标题开新页，一级标题则成为节分隔符，在 Beamer 的 PDF 导航里给页面分组。驱动 Marp headingDivider 的那套大纲纪律同样驱动 Pandoc，只多一层：节。分三部分的季度汇报，读起来就是三个分组的节。

PDF 输出的模板是 LaTeX Beamer，主题只是一个变量：pandoc talk.md -o talk.pdf -t beamer -V theme:Madrid -V aspectratio:169 --pdf-engine=xelatex。Madrid 是保守之选，Metropolis 是素净的现代款，后者需要 xelatex 或 lualatex。PDF 出自 LaTeX，成品是字体已内嵌的矢量文本——可搜索、任何投影仪上都锐利、数学公式原生渲染。

那这条路什么时候赢？当片子只是批量产物之一——一个 CI 任务连夜渲染文件夹里的每份报告、简历和片子。以及当演讲是学术场合，Beamer 的引用和公式处理没有对手。

代价也是 Pandoc 转换路径一贯的代价：更强的控制和模板能力，换来的配置和模板调试。已经在维护 Pandoc 模板的团队做幻灯片几乎免费；其他人从 Marp 起步。

4. Slidev 与 Reveal.js——开发者向的另两个选择

Marp 和 Pandoc 优化的是「写完即导出」的简单。另两个开发者向的框架站在交互端——Reveal.js 和 Slidev——在四个工具之间做选择，比的其实不是渲染质量，而是演讲需要多少运行时行为。Reveal.js 是老将，一个直接编写的 HTML 框架，Markdown 内嵌其中；Slidev 是它 Vue 时代的 Markdown 优先后代，围绕开发者演讲和现场代码而造。

差异集中在几个维度上：

Reveal.js 适合把浏览器当舞台的片子：键盘驱动的总览模式可以跳到片中任意位置，fragments 支持逐元素计时，还能写自定义 JavaScript。代价是源文件首先是 HTML 文档——Markdown 活在 <section> 标签里，主题是你自己维护的 CSS 文件。有前端深度的团队得到四个之中表达力最强的片子；其他人得到的是功课。

Slidev 是开发者演讲的中间路线：Markdown 书写、v-click 指令实现的真 fragments、逐行代码聚焦，导出套装里还有一个可部署的单页站点。它的 PPTX 导出和 Marp 一样依赖页面图片而非原生文本。选择规则很短：从不需要动画，选 Marp；已经用 Pandoc 单一源，留在原处；围绕演进中的代码和点击分步的开发者演讲，Slidev；要完全掌控浏览器且前端时间充裕，Reveal.js。

5. 从十行大纲到八页片子

这套工作流放在真实产物上最容易看清。拿季度汇报举例——那种周一是会议记录里的十行字、周四就要讲出去的片子。写成大纲，原材料是这样的：

# Q3 复盘

- 营收 420 万，计划 380 万
- 流失率 2.1% -> 1.4%
- 企业版延期到 Q4
- 补救：砍 SSO 范围，先上计费修复
- 两位资深工程师到岗
- Q4 重点：定价改革、SOC 2 审计

第一个决策：页面怎么切。六条要点可以配六个 ---，但更干净的映射跟着文档结构走——一页标题，然后每个主题一页。上面的大纲变成八页：标题、营收、流失、延期事项、补救计划、招聘、Q4 重点，外加一页附录，放那个每季度都有人问的招聘细节。

第二个决策：什么配得上独立一页。营收和流失虽然是两个指标，仍然分开放，因为每个数字在被讨论时都值得独占屏幕。延期单给一页，补救计划再单给一页——把延期埋进指标网格里读起来像遮掩，而复盘材料恰恰是最不能被这样解读的场合。这些页面每页只有三行：一个标题、一个数字、一句支撑。

第三个决策：视觉由谁承担。营收图从仪表盘导出为 PNG，走 bg right:50% 的图片修饰符进场，数字就坐在自己的曲线旁边。页面下方的演讲者备注写着「数字未经审计」——这类上下文跟着片子进现场，但永远不会出现在屏幕上。

总耗时：二十分钟上下，大部分花在决定删什么。回报在下个季度复利：同一份文件和这次 diff，差异就是故事本身——流失率又降了，产品上线了。幻灯片文件做不出这种对比；文本文件免费送你。

6. 导出矩阵：PDF、PPTX 与 HTML

选导出格式，就是选哪些属性能在「从文件到讲台」这一程里活下来。下表是截至 2026 年各目标格式的真实状态，除注明外以 Marp 为渲染引擎：

有两行干的活最多。字体这一行解释了为什么图片型 PPTX 是一个兼任优点的缺陷：文本不可编辑，但片子在任何机器上渲染一致，投影仪字体轮盘赌就此终结。Marp CLI 提供经 LibreOffice 中转的实验性可编辑模式，Pandoc 的 PPTX 则一直是原生文本框——但如果导出后的重度编辑才是真实工作，在 PowerPoint 里创作仍是诚实的答案。Beamer 同时是两行的例外：它的 PDF 是原生矢量文本，\note 行也可以印到备注页上。

务实的会议配置直接从矩阵里掉出来：U 盘里放 PDF 作主力，HTML 导出作备份、演讲者备注完整，任何环节都不依赖会场 WiFi。内部片子的算法则反过来——HTML 赢，因为备注视图免费，文件又和它呈现的论证住在同一个仓库里。

7. 三种常见翻车与绕法

每套文本片子工作流都会早早撞上同样三种翻车。没有一种是致命的，每一种的绕法都比原版式问题在设计工具里要花的时间更少。

7.1 图片路径静默失效

图片路径按 Markdown 文件的位置解析，失效时没有任何警告——渲染出来的片子上，图表位置是一个碎图占位。经典成因：片子挪了文件夹、CI 检出的目录结构不同、或者 HTML 导出撞上浏览器的本地文件安全规则。解法是纪律加一个开关：图片资产和片子放同一个仓库、同一个文件夹里，从本地检出导出时传 --allow-local-files。团队的 Markdown 本身还不牢的话，markdown 速查表一个下午能修好的片子 bug，比任何工具迁移都多。

7.2 代码溢出页面边界

四十字符的终端行，在可读的字号下塞不进 16:9 的一页；把字体缩到塞得下，是用观众的视力换完整性。更好的绕法是文本工具天然鼓励的那种：把代码清单拆到两页，每页只出现关键的那几行，副作用是演讲速度降到理解速度。第二步是修剪——活下来的代码页，都是没用的东西已经被删干净的页；主题的代码字号留到最后再动。代码真的需要滚动，那它属于现场演示或讲义，不属于页面。

7.3 表格需要第二页

十二行的表格在编辑器里可读，在会议室第六排就不可读了，因为画布不滚动。绕法按优先级排：把表格砍到论证需要的那三行，完整版用文档链接出去；在自然边界处拆成两页；或挪到附录页，有人问再翻。搭精简版时，markdown 表格语法就派上用场了——列数才是真正的预算，第五列之后的每一列，后排都读不见。

8. 文本幻灯片做不好什么

对天花板诚实：重图片、重设计的片子——市场 keynote、大会视觉、任何依赖精确品牌版式的材料——是错误的用例。文本驱动的工具应用主题；它们不做艺术指导。如果某一页的信息依赖一张图片精确占据画布的某个百分比、文字环绕其侧，那一页（或者整份）请用设计工具。

还有演示习惯的调整：并非每种导出格式都有与 PowerPoint 对等的演讲者备注视图，围绕 .pptx 建立的排练流程也无法照搬。提交前先确认导出目标支持你的演示配置——截至 2026 年，PDF 和 HTML 是最稳的导出；.pptx 输出真实存在但比原生 PowerPoint 简朴。

9. 文本幻灯片的决定性优势场景

技术分享和内部汇报是甜点位，原因有三条且相互叠加。片子像代码一样被评审——同事可以在 pull request 里对某一页的文字写评论。临时改动是文本编辑而不是排版手术——前一晚 23:50 修一个数字是安全的。AI agent 可以原生起草、重组、收紧幻灯片大纲，因为大纲就是 Markdown——Mermaid 图表受益的是同一个协作循环。

所有这些背后是同一个模式：当价值在论证里，就把论证留在文本里，让工具去渲染。

10. 结语

Markdown 转幻灯片不是要取代设计师手里的 PowerPoint。它移除的是「内容即文字」的那类幻灯片——技术分享、状态汇报、内部评审——的排版税，并让这些片子进入你其余文本工作流所在的同一个可版本化、可评审、可与 AI 协作的世界。

拿这个月你要讲的最小的一份片子试一下：写大纲，渲染，然后注意时间都花在了哪。