轻松制作嵌入文章和文档的 Slide Deck

Markdown Slides 让一份 Markdown 页面成为可以嵌入文章或文档的交互式 deck，同时完整保留为可阅读页面。上面这份 deck 不是外部 PowerPoint，也不是单独维护的演示文件。它是本站的一份 Markdown 页面，直接放在本文中。播放器提供一条短路径，下面的正文提供一条长路径；两者来自同一份内容对象。

观点仍然属于作者

在已经启用 Slides 的站点中，内容作者只需要使用普通 Markdown。作者可以自己写，也可以把 AI 当作编辑工具，帮助整理、压缩和维护表达。Slides 不是一项会替作者发明内容的内置 AI 功能；它只是让作者已经拥有的 Markdown 可以同时用两种形态呈现。

Same record: readable page and presentation player.

AI 可以帮助把大纲变成清楚的 Markdown、安排页面顺序，也可以把一个观点解释成不同形态。它不能替作者承担“哪个观点值得提出、一个说法是否为真、作者真正想表达什么”这些判断责任。这些仍是作者的工作。

这也是为什么一份内容对象很重要。作者可以专注于内容的精华，AI 则帮助把表达变得更容易读、更适合短讲，或更适合放入文档。当内容本身变化时，只需要维护一份记录，而不是分别维护一套 slides 和一篇文章，最后让两者慢慢漂移。

同一份内容，两个入口

Slides 的正文仍然是普通 Markdown。文件开头的一对 --- 用来包住 front matter；在它之后的正文中，用空行包住的一行 --- 才是新一页。Web Device 将这些页渲染成播放器和文字稿两种形态。读者可以在页面里的 16 比 9 播放器中翻页，也可以沿着下方的文字稿继续阅读；使用全屏按钮、播放器获得 focus 时按 f，或打开带 ?full 的链接，才会进入演示模式。

这让 presentation 不再是一份只能在会议中使用的附件。它可以作为页面的一部分被引用、被嵌入，也可以在需要时用演示模式打开。文字稿仍是内容本身，不是播放器失效时才出现的备份。

如果一页需要讲稿提示，把单独一段 HTML 注释放在这页中即可。备注会留在文字稿对应的位置，不会投到幻灯片上。它适合补充公开的讲述语境，不是私密的演讲者备注。这样，面对读者的内容和帮助讲述的内容仍在同一份源文件中，但不会混在同一个画面里。

先写页面，再让形式跟着内容走

先在文件开头的 front matter 中写 slides: true，让正文里的顶层分隔线成为分页。这一项本身会保留可读文字稿。站点已经提供播放器 named layout 时，再写 layout: slides 选中它。两者不是同一个开关：前者决定正文如何分组，后者把已经配置好的播放器加到页面上。

源文件仍是普通 Markdown，作者可以直接写，也可以让 AI 帮助调整结构和讲解方式。它不是另一套必须单独学习、单独维护的可视化创作系统。

---
title: Explain one thing clearly
slides: true
layout: slides
---

## 先说清一个观点

这一页仍是一段普通 Markdown。

<!--
这里是讲稿备注，只会出现在文字稿中。
-->

---

## 再展开下一步

站点开发者只需一次性启用播放器和对应的 named layout。这是站点配置，不是每位内容作者的工作。配置完成后，作者只需选择已有的 layout: slides，然后继续写普通 Markdown。播放器会沿用站点已有的颜色、字体和间距，因此作者不用另加一套主题或组件库。如果站点还没有启用 Slides，仍可保留 slides: true 的可读文字稿，并请站点开发者先启用播放器，再期待它出现。精确的站点配置见Markdown Slides 使用指南。

把 deck 放进一篇文章

当这份 Slides 已经有同站页面地址时，用显式的 embed directive 把它放进文章或文档。这里填写的是 deck 的同站绝对路径，例如下面的路径；它不是把任意外站页面嵌进来的通用方式：

::embed{url="/zh/docs/web-device/slides-overview/"}

播放器初始化后，嵌入框的可见表面是一个 16 比 9 播放器，读者可以直接在其中浏览。直接打开 deck 自己的页面时，播放器和完整文字稿都会出现。两种入口指向同一份内容，不需要在文章里另贴截图，也不需要复制一遍 slides 文案。

播放器不是第二份内容。它让同一个观点拥有简短、可交互的形态，同时不拿走可阅读的文章或文档。

继续阅读：Markdown Slides 使用指南。