用 Slidev 将 Markdown 变成开发者友好的幻灯片

每次技术分享或者答辩前我都要跟 PPT 较劲半天代码块怎么排版才能清晰又不占地方动画效果怎么加才不显得花哨配色怎么调才配得上“极客风”。用 PowerPoint 或者 Keynote 给开发者讲东西总有种穿着西装去修服务器的不对味感。后来我换成了 Slidev一个基于 Markdown 的演示文稿工具才终于觉得“对了”。这东西能把幻灯片当成一篇可版本控制的 Markdown 文档来写代码高亮、Vue 组件、演讲备注、录制视频统统内置特别适合技术分享、项目汇报、开源项目路演这类场景。如果你也是被模板和格式折腾过的开发者这篇就聊聊我为什么换掉传统 PPT以及一套能直接上手复刻的 Slidev 实操流程。1. 先想清楚为什么是 Slidev 而不是 PowerPoint1.1 传统演示工具的“开发者痛点”在哪里先摊开讲我自己的痛点。PowerPoint 和 Keynote 功能确实强大但它的核心工作流是“鼠标拖动”先在画布上摆文本框再一点一点调对齐、字体、大小等调完版式写内容的时间已经耗了一半。到了代码环节更痛苦从 IDE 往 PPT 里贴代码格式经常乱掉字号调小了看不清调大了又换行想做一个行高亮要么手工涂色要么用插件整个流程被切得稀碎。最要命的是版本管理一份 PPT 文件是二进制格式想在 Git 里看 diff 几乎等于做梦。多人协作时同事改了哪一页、改了哪些内容全靠口口相传。我身边的大部分开发者其实都有类似的感受不是不会用 PPT而是觉得这套工具链跟自己的工作方式离得太远。开发者习惯的是“用文本描述结构”是“一切皆文件”是“命令式操作”而不是在画布上一个点一个点地挪元素。Slidev 恰好把演示文稿的生产方式拉回到了开发者最舒服的轨道上写 Markdown加载为幻灯片所有效果用代码控制。1.2 Slidev 的核心工作逻辑Markdown 即幻灯片Slidev 不是又一个“在线模板站”它本质上是一个基于 Vite 和 Vue 3 的应用你写的slides.md就是整个演示文稿的源文件。每个 Markdown 中用---分隔的区块最终会被渲染成一页独立的幻灯片。默认的分隔符是---全文的 Frontmatter 放在文件开头用 YAML 格式写页面级的配置则写在每个区块的 Frontmatter 里。--- theme: seriph title: 我的技术分享 --- # 第一页标题 - 项目背景 - 核心方案 - 效果展示 --- # 第二页标题 这里放第二页的内容只用记事本就能快速产出一个能跑起来、有动画、有高亮的演示文稿这是 Slidev 最核心的吸引力。从“拖动元素”到“书写代码”这种转换看似只是形式变了实际上改变了创作节奏你可以先把内容和逻辑写通顺再来调整样式、动画、布局。这也让幻灯片回归到了“内容为王”的本质。1.3 横向对比它跟同类工具有什么区别市面上基于 Markdown 做幻灯片的工具其实不少比如 Marp、Reveal.js、Remark。Slidev 的差异化主要有三点对开发者生态友好支持安装 npm 主题、导入组件、使用 UnoCSS 任意写原子类样式。相当于所有前端基建都能直接拿进幻灯片里用写 Vue 组件就等于做了一套可复制的自定义模板。内置开发服务器和热更新基于 Vitenpm run dev启动后改 Markdown浏览器里即时生效旁边还能实时看到演讲者备注和下一页预览。一体化的演示辅助能力演讲者模式、录制摄像头画面、导出 PDF/PPTX/图片、一键部署到静态托管平台这些是 Marp 和 Reveal.js 通常需要二次折腾的功能。工具学习成本自定义能力动画与组件导出能力PowerPoint / Keynote低中强强Marp低中弱中Reveal.js中高高中中Slidev中很高强强如果你只想把 Markdown 快速变成一页页静态 PDFMarp 就够了但如果你想在演示过程中使用代码高亮、组件复用、现场录制Slidev 是更顺手的选择。2. 核心细节解析安装、目录结构与第一页幻灯片2.1 环境准备与项目初始化Slidev 要求 Node.js 版本在 18 以上。我在不少同学电脑上遇到旧版本跑不起来的情况所以建议先用node -v确认版本太老的话直接用 nvm 切到 LTS 版本。初始化项目有两种方式。第一种是在终端里快速创建一个空目录npm create slidevlatest命令会交互式询问项目名称、是否安装依赖等按提示选完进入项目目录执行npm install再npm run dev浏览器访问http://localhost:3030就能看到默认的第一页幻灯片。第二种方式是把 Slidev 装进现有前端项目npm install slidev/cli slidev/theme-default npx slidev这种方式适合已经在维护某个开源项目想给 README 或者仓库文档配套一个介绍 slides 的场景。我初期更推荐第一种目录干净不会跟其他依赖纠缠。2.2 理解 slides.md 的分页与 Frontmatter新建项目的根目录就是入口默认有一个slides.md。打开它你会看到最上方有一段被---包裹的内容这是整份文稿的全局配置--- theme: default title: Slidev 分享 info: | ## Slidev 演示文稿 面向开发者的效率工具分享 class: text-center drawings: persist: false transition: slide-left mdc: true ---常用配置项可以这样理解theme指定主题包名title是浏览器标签页和导出文档的标题info写在备注里可作为演讲提示transition控制页面切换动画class给整页加样式类。如果某页想单独使用不同布局就在对应页面的---中写页面级 Frontmatter页面级的优先级高于全局。分页的本质是 Markdown 的区块拆分。写的时候有一条实用准则一页只讲一个核心点。不是因为技术受限而是因为幻灯片本来就是“信息漏斗”一页塞太多东西后排观众根本来不及消化。2.3 第一个可复现的 slides.md 示例下面这份是我给一次内部技术分享准备的最简版本覆盖了标题页、列表页、代码页、结束页可以直接复制到slides.md里体验--- theme: seriph title: Slidev 实践分享 info: | 用 Markdown 制作开发者友好的幻灯片 class: text-center --- # Slidev 实践分享 用 Markdown 写幻灯片 简洁 / 可版本管理 / 对开发者友好 div classpt-8 kbd空格/kbd 进入下一屏 /div --- # 目录 - Slidev 为什么适合开发者 - 核心功能实操 - 常见问题排查 - 部署与导出技巧 --- # 代码高亮示例 ts {2-3} function fibonacci(n: number): number { if (n 1) return n; return fibonacci(n - 1) fibonacci(n - 2); }花括号里的 2-3 表示代码第 2 行到第 3 行会被高亮显示。小结内容与样式分离像写代码一样做演示文稿导出方便不怕现场格式错乱启动后从第一页按空格一直翻到最后一页你就完成了从 0 到 1 的 Slidev 体验。这里最吸引我的是 {2-3} 这种行高亮语法讲代码时圈重点再也不用截图标红框了。 ## 3. 实操过程与核心环节实现 ### 3.1 布局、主题与组件让幻灯片不“千篇一律” Slidev 默认提供了几种布局可以通过 Frontmatter 的 layout 字段切换比如 cover、center、two-cols、section。最常用的两个是 center 和 two-cols。 two-cols 讲义式的左右分栏在对比方案时特别好用 markdown --- layout: two-cols --- # 左侧内容 - 方案 A - 优点 - 缺点 ::right:: # 右侧内容 - 方案 B - 优点 - 缺点除了官方自带的布局Slidev 还支持把任意 Vue 组件直接用进 Markdown。比如我在分享架构设计时经常需要画一个简单的架构框我不会再贴一张截图而是在组件目录里写一个ArchGraph.vue再在 Markdown 中ArchGraph /引入。这样架构改动时只要改组件里的数据所有页面自动更新永远不会出现“图跟代码不符”的情况。主题方面官方有slidev/theme-default、slidev/theme-seriph社区也有大量主题比如slidev/theme-apple-basic。如果你对设计有自己的偏好也可以直接在全局样式文件里覆盖 CSS 变量Slidev 里很多颜色都是通过 CSS 变量控制的改起来比从头写样式快得多。3.2 代码高亮与“讲代码”的专属姿势给开发者做演示代码是屎山里的硬骨头。Slidev 内置了基于 Shiki 的代码高亮支持的语言非常多从 JavaScript、Python、Rust 到 Go 都能识别。常用语法有这么几种# 高亮第 2 行 js {2} # 高亮第 2 行到第 4 行 js {2-4} # 高亮第 2 行和第 5 行 js {2,5} # 带行号显示从 10 开始编号 js {lines: true, startLine: 10}startLine这个参数很实用比如你只需要讲一个 200 行文件里的其中 10 行可以用它把起始行号设为真实代码的对应行数观众不会觉得“这里的i是哪来的为什么从 1 开始”。对于更复杂的交互式演示CodeBlock组件还能配合editable属性做成可编辑代码块观众现场提需求你直接在幻灯片上改代码并重新运行如果接入了前端演示工具链。我一般不用这个功能因为现场容易翻车但如果是录屏教程它非常好使。3.3 绘图、图标与 MDC 语法MDCMarkdown Component语法是 Slidev 的一个增强特性需要在slides.md的全局配置里开启mdc: true。它允许你在普通 Markdown 文本中直接使用 Vue 组件和快捷样式比如::block{} # 一级标题可以这样写 :br 这里用 ::block{} 包裹了一个块级容器适合做局部样式隔离。图标方面Slidev 内置了carbon和ph两套常用图标库格式是carbon:rocket /或ph:rocket-duotone /。写类型说明、标注流程箭头时图标能大大减轻纯文字带来的沉闷感。绘图的话如果你想画架构图默认支持 Mermaid 语法mermaid代码块直接渲染成图和 PlantUML。不过我自己很少在演示文稿里用 Mermaid因为太复杂的图会喧宾夺主。大部分架构图我选择用two-cols加左右对照观众注意力更集中。3.4 演讲者模式、快捷键与远程协作进入演示模式后按p可以打开演讲者模式演讲稿、当前时间、下一页预览都会显示出来按f可以切换全屏按s打开“演讲者窗口”你可以把演示窗口投到前台大屏把演讲者窗口留给自己。b是黑屏键临时让大家讨论问题时特别好用。Slidev 还支持按左右方向键翻页上下方向键可以“步进式”浏览一页里的动画元素。有些演示文稿我故意不把所有内容一次性展示而是用v-click指令逐条出现这样观众的注意力始终跟着我走。v-click的用法非常直接- 第一条内容 v-click - 第二条内容 v-click点击一下显示第一条再点显示第二条不需要额外配置动画曲线就能形成自然的递进效果。3.5 导出与部署PDF、PPTX 和 GitHub PagesSlidev 的导出能力是我敢把它用在正式场合的重要原因。导出 PDF 的命令如下npx slidev export它会自动用无头浏览器逐页渲染后生成 PDF。如果某一页有复杂动画导出时会保留最终状态这个要提前检查。导出 PPTX 则需要额外安装slidev/export-pptx插件npm install slidev/export-pptx npx slidev export --format pptx导出 PPTX 的主要意义是方便传给那些非要一份.pptx文件的协作方但里面部分复杂组件可能无法完美还原成原生 PPT 元素只能算“可用”。因此我默认还是优先交付 PDF。部署到 GitHub Pages 时构建静态文件就用npx slidev build构建产物在dist/目录可以整体推到任意静态托管平台。如果遇到图片路径 404 的情况多半是因为在slides.md里用了相对路径而构建后的站点目录层级变了建议把图片放到public/目录下并用绝对路径引用比如/screenshot.png。4. 常见问题与排查技巧实录4.1 安装和启动阶段的问题端口被占用默认端口是3030如果本地已有一个服务占用启动会报错。解决办法是用--port参数换一个端口npx slidev --port 8080Node 版本太低项目推荐 Node 18 及以上。如果npm install时报语法错误或依赖装不上先用nvm install 18或nvm use 18切到高版本。依赖安装缓慢或失败国内网络环境访问 npm 官方源确实慢有些人会换源但我更建议用npm install --registryhttps://registry.npmmirror.com只给当前项目换源避免污染全局配置。4.2 内容渲染和样式问题代码块不换行且溢出长代码默认容易溢出屏幕解决办法是开启代码块横向滚动或者手动换行并利用{lines: true}显示行号让观众明确知道换行后的归属。图片不显示优先把图片放入public/目录再用/images/xxx.png引用。如果在本地能看到、部署后看不到那必然是在 build 后的路径不一致这时先检查base配置。GitHub Pages 部署需要特别注意仓库名路径通常需要在构建命令里加参数npx slidev build --base /repo-name/动画不生效检查是否在slides.md中启用了transition以及v-click是否正确闭合。某些旧版本的浏览器对 Web Animations API 支持不好更新浏览器或禁用复杂过渡可以解决。4.3 导出和演示现场问题导出 PDF 时字体被替换或中文乱码Slidev 导出的底层无头浏览器不会自动安装你本机的中文字体需要在系统里安装好需要的中文字体比如思源黑体。否则 PDF 里的中文可能变成方框。推荐在全局样式中显式指定字体族html, body, #app { font-family: Source Han Sans CN, PingFang SC, Microsoft YaHei, sans-serif; }导出时图片模糊或布局溢出npx slidev export默认使用视口大小导出如果页面内容超过了视口PDF 里就会溢出。先用浏览器打开演示文稿按F11全屏预览一遍确认所有页面没有横向滚动条再导出。现场投影比例不对在slides.md中设置aspectRatio: 16/9或aspectRatio: 4/3投影仪如果突然不支持 16:9只能临时在浏览器里缩放或者提前导出 PDF 当后备方案。我遇到过几次现场 HDMI 输出异常这时 PDF 就是救命稻草。4.4 几个很容易被忽略的实用技巧备注区在每页 Markdown 的末尾用!-- 这里是备注 --写备注演讲者模式里才会显示观众看不到。这是一个练习演讲和埋梗的好地方。本地录制Slidev 支持录制演讲者摄像头画面命令是npx slidev record它会输出一个视频文件可以直接作为线上分享的回放素材。用---做垂直分隔同一个页面内部想制造切换动画可以使用---加上v-click这种“同一页多屏展示”的方式适合一个模块内部的递进讲解。主题覆盖与其从零写主题不如npm view slidev/theme-*搜一下现有的主题选一个接近的风格再微调。5. 我最后想分享的一点体会用了大半年 Slidev 之后我再也没法心安理得地打开 PowerPoint 排模板。最直观的变化不是“做幻灯片变快了”而是我敢随时改幻灯片了。以前改 PPT 要重新导出、重新传群文件现在直接在slides.md里改一行文字保存浏览器就刷新分享出去的链接也同步更新。如果你要负责一次技术分享、项目复盘或者开源路演我建议花两个小时把 Slidev 跑通。别急着堆功能先写七八页 Markdown把标题、列表、代码高亮、演讲者模式用熟你会发现做演示文稿这件事终于不需要离开终端了。