Kadal Deck

Kadal Deck

用 MDX 撰写演讲稿，在浏览器中进行演示。让现场观众通过手机跟随演示、投票和提问。

_{体验之旅，引擎自己的功能演示文稿：包含 100 多页幻灯片，全部使用 MDX 编写。打开后按 ?。}

快速开始 · 文档 · 在线体验 · 主题 · 托管 · 更新日志

---

30 秒快速开始

需要 Node 20.19 或更高版本。

npm create @kadal/deck@latest my-talk
cd my-talk && npm install
npm run dev        # http://localhost:5173: edit deck.mdx and the slide you're on updates in place

一份演示文稿就是一个 deck.mdx 文件：使用 Markdown 编写，以 --- 分隔幻灯片，并可按需添加组件。

---
title: Hello, room
theme: ocean
---

# Hello, room

---

## One point at a time

<Clicks>

- Slides split at `---`; a slide below this one starts at `----`
- Code steps line by line, and the notes follow your clicks

</Clicks>

---

<Poll id="lunch" question="Lunch?" options={["Dosa", "Biryani", "Both"]} />

准备就绪后：

npx kadal-deck build      # dist/: a static site for any host, works offline
npx kadal-deck export     # PDF in export/ (add --png or --pptx)
npx kadal-deck publish    # a URL on deck.kadal.cc with a live room (free plan)

已有 Slidev 演示文稿？运行 npx kadal-deck import slidev slides.md 即可转换，并生成一份报告，列出所有未能迁移的内容。

你将获得什么

编写 (文档)	MDX 幻灯片、19 种带命名插槽的布局、每张幻灯片的 frontmatter、src: 引入、编译器会在术语首次出现时添加链接的术语表
点击与动效 (文档)	<Click>、<Clicks>、at="+2"、跟随点击显示的备注、7 种转场效果（可为进入和退出分别选择不同效果）、自动动画、<Motion>
代码 (文档)	Shiki 逐行显示高亮效果、magic move、Monaco 编辑器、可运行的 JS/TS/Python、TwoSlash 悬停提示、代码组、代码片段导入
数学、图表与草图 (文档)	构建时使用 KaTeX、采用演示文稿配色的 Mermaid、逐区域显示的 Excalidraw 绘图
外观 (文档)	16 种主题，支持浅色和深色模式；42 种背景（大多数为动态背景）；通过 Iconify 使用 200,000 个图标；Tailwind
任意框架 (文档)	内置 React 和 Web 组件；Vue、Svelte、Solid、Preact、Qwik、Angular、Fresh、Rust/WebAssembly 和 Python 作为岛屿，仅在对应幻灯片出现时加载
演示 (文档)	演讲者视图，包含备注、计时器和下一张幻灯片；绘图、激光笔、聚光灯、黑屏、摄像头、录制；视频通话分享窗口；手机遥控器；vim 按键
现场互动室 (文档)	观众通过手机跟随演示：回应、可点赞的问题、投票、词云、限时测验、节奏表盘和举手功能
导出 (文档)	导出 PDF、PNG 和 PPTX，可包含或排除每个点击步骤；生成可离线使用的静态构建

演讲者视图与观众的手机

备注会随着每次点击高亮显示，还有下一步内容、节奏计时器，以及集于一屏的所有工具。在任意演示文稿中按 S。	扫描二维码即可使用：无需应用，也无需账号。幻灯片会与你同步，也可以提前浏览，之后再赶上进度。

## 主题

共有 16 款主题，在适用的情况下均提供浅色和深色版本。其中 3 款为内置主题，其余主题需安装为软件包，并在 frontmatter 中指定名称（theme: ocean）。前往 deck.kadal.cc/themes 浏览全部主题。

minimal · 内置	rla · 内置	stack · 内置	ocean
brand	crayon	folio	lecture
neon	swiss	terminal	classic
seriph	crisp	bricks	shibainu

Classic、seriph、crisp、bricks 和 shibainu 是基于官方 Slidev 主题移植而来，采用 MIT 许可证，并在各自的软件包中注明作者。运行 npm create @kadal/deck@latest -- --theme <name> 即可创建自己的主题；规范见 THEMES.md。

面向 AI Agent

Kadal Deck 既可以由你编写，也可以由 Agent 编写：它提供一项教会 Agent 如何使用此格式的技能、一个能逐行编辑幻灯片并渲染内容以便 Agent 查看成果的 MCP 服务，以及一个每条命令都以 JSON 格式响应的 CLI。指南：AI Agent。

/plugin marketplace add kadalcc/deck          # Claude Code: the skill and the MCP server together
/plugin install kadal-deck@kadal-deck

npx skills add kadalcc/deck                              # the skill alone, for any agent (skills/kadal-deck)
claude mcp add kadal-deck -- npx -y @kadal/deck mcp      # the MCP server alone

在 Claude Desktop、Cursor 和 VS Code 中，将客户端指向 npx -y @kadal/deck mcp。服务会在其启动所在的文件夹中工作（或使用 --dir <path>），除非使用 --allow-outside 启动，否则绝不会在该文件夹之外读取或写入内容。

MCP 工具
deck_reference、deck_frontmatter_schema	引擎自有目录中的所有组件、布局、背景和选项
deck_create、deck_outline、deck_read_slide、deck_check	创建脚手架、以结构形式读取幻灯片组、检查代码
slide_add、slide_update、slide_remove、slide_move、deck_update_frontmatter、notes_set	仅修改对应幻灯片行的编辑，并即时检查代码
slide_render、deck_preview	由开发服务器生成的幻灯片 PNG；该服务器会在调用之间持续运行，并提供实时 URL
deck_build、deck_export、deck_publish	静态站点、PDF/PNG/PPTX，以及已发布的幻灯片组

对于脚本：使用 kadal-deck check（出错时退出码为 1）、kadal-deck screenshot、kadal-deck info [topic]，并在每条命令中使用 --json。退出码：0 表示成功，1 表示失败，2 表示用法错误，3 表示尚未登录，4 表示缺少前置条件。@kadal/deck/catalog 提供幻灯片组可用的所有数据，@kadal/deck/authoring 可将幻灯片组作为文本读取、检查代码和编辑，而 @kadal/deck/schema/frontmatter.json 是 frontmatter 的 JSON Schema。

在编辑器中

• VS Code 扩展（Marketplace）：实时预览会跟随光标移动；可拖动幻灯片大纲调整顺序；为所有设置和组件提供 IntelliSense；将幻灯片组的检查结果显示为问题，并支持格式化。
• @kadal/prettier-plugin：适用于幻灯片组文件的 Prettier，可用于任何支持运行 Prettier 的编辑器。kadal-deck format 无需配置即可运行相同的格式化工具。
• 在浏览器中：在 kadal-deck dev 中按 E，即可在当前幻灯片旁打开编辑器。

工作原理

每张幻灯片都是独立模块，因此编辑时只会重新渲染一张幻灯片，而非整个幻灯片组。绘图是一个 Excalidraw 文件，使用与幻灯片 <Sketch> 相同的草图 DSL 绘制。

托管或自托管

编写、演示、演讲者视图、导出和静态构建只需此引擎即可完成，而且始终免费。实时房间需要一台为每个幻灯片组维护 WebSocket 连接的服务。

• deck.kadal.cc：运行 npx kadal-deck publish，即可为幻灯片组创建 URL、实时房间、分析数据、密码、版本历史和团队；还可在网页上快速编辑，并通过 kadal-deck pull 将更改逐张合并回文件。提供免费方案，付费方案则为引擎提供资金支持。
• 你自己的主机：kadal-deck build 的输出可运行在任何静态主机上（kadal-deck ci 会生成适用于 GitHub Pages、Netlify、Vercel、Cloudflare 或 Docker 的部署文件）。房间协议在 @kadal/deck/protocol 中进行了类型定义，并且逐个端点提供了文档；kadal-deck relay 则可为静态构建提供手机遥控功能。

Packages

Package	Version
@kadal/deck		引擎：MDX 编译器和 Vite 插件、运行时、组件、主题、实时客户端、导出功能、kadal-deck CLI 和 MCP 服务
@kadal/create-deck		npm create @kadal/deck@latest：创建新演示文稿、主题或扩展
@kadal/deck-vue, -svelte, -solid, -preact, -qwik, -angular, -fresh, -wasm, -python		用于 islands 的框架渲染器
@kadal/theme-*（13 个包）		上述主题
@kadal/prettier-plugin		用于演示文稿文件的 Prettier
Kadal Deck for VS Code		预览、大纲、IntelliSense、检查和格式化
@kadal/deck-shell	尚未发布到 npm	预构建页面，可在浏览器中运行编译后的任意 deck.mdx，供托管方和编辑器使用

所有 @kadal/* 包使用相同的版本号，并通过本仓库的 发布工作流 使用 npm 可信发布进行发布，每个 npm 页面都附有 来源证明。VS Code 扩展通过其独立工作流发布。

文档

快速入门 · 编写幻灯片 · 组件 · 配置 · CLI · 发布 · 编写主题 · 从 Slidev 迁移

引擎的完整参考文档涵盖所有组件和选项，见 packages/deck/README.md；运行 npx kadal-deck info 可在终端中查看。

许可证

AGPL-3.0-or-later。使用 Kadal Deck 进行演示、自行托管演示文稿，或在你发布的网站中嵌入演示文稿，都不会触发任何义务；你无需向任何人支付费用。如果你将修改过的引擎作为网络服务运行，其用户必须能够获取你修改后的源代码。

想基于此引擎构建托管产品或专有产品，却不想公开你的更改？商业许可证可免除 AGPL 义务：请发送邮件至 [email protected]。详情见 LICENSING.md。移植的 5 个主题采用 MIT 许可证，第三方声明见 THIRD_PARTY_NOTICES.md。

贡献

附上能够复现问题的小型 deck.mdx 的错误报告最有帮助，也欢迎提交拉取请求。CONTRIBUTING.md介绍了环境设置（Bun 1.3+）、测试和 island 验证器。问题和想法请前往 Discussions。请遵守 行为准则，并按照 SECURITY.md中的说明私下报告安全问题。

赞助

赞助款用于支持开源引擎的开发时间：处理问题、完善文档、开辟新的岛屿，以及开发你所需要的功能。在 GitHub 上赞助 Kadal Deck；赞助档位及各档位对应的权益见 deck.kadal.cc/sponsor，支持者名单见 BACKERS.md。公司可以通过发票赞助。

在此展示贵公司的徽标： 成为首家赞助 Kadal Deck 的公司。

_{由 Kadal 在金奈打造 · Kadal · deck.kadal.cc · [email protected]}