刚接触 Markdown 的人通常把它当作写笔记的工具做幻灯片时很少会第一时间想到它。但 Markdown 幻灯片的核心优势并不在于“能写字”而在于把演示文稿降到纯文本的抽象层级每一页就是一个文本单元尺寸和样式交给主题内容本身可以被版本管理、被 AI 批量生成、被脚本自动导出。再加上 AI 辅助之后你不需要从空白页开始写提纲也不需要边查格式文档边排版只需要给模型一个题目和页数再对生成的 Markdown 做裁剪和校对就能得到一版结构完整、可渲染、可导出的幻灯片。这篇文章会沿着一条可执行的工作流展开先从概念上理解 Markdown 如何转换成幻灯片然后搭好本地环境再让 AI 生成草稿并修正成合格的 Marp 语法接着完成预览、导出和自动化构建最后给出常见问题的排查路径和一套适合团队使用的检查清单。整个过程中AI 不只是“帮我把一页内容扩写一下”而是可以作为内容策划、讲稿生成器和格式预处理工具来使用。1. 用 Markdown 做幻灯片先理解“内容”和“表现”是怎么分离的很多人在试用 Markdown 幻灯片工具时第一反应是“这和 PPT 有什么不同”。PPT 的交互模型是先建一个画布再放文本框、图片框、形状然后逐个微调坐标。Markdown 的交互模型相反先写内容再给内容标上结构最后由主题决定视觉呈现。这个差异决定了整个使用方式。1.1 Markdown 如何表达“一页”在传统写作中Markdown 用#标题、列表、段落来组织文本。在幻灯片场景里还需要一个额外的抽象分页符。常见的做法是使用---三个连字符作为页与页之间的分隔线。一个最基本的 Marp 幻灯片长这样# 第一页标题 这是第一页的内容。 --- # 第二页标题 - 这里是第二页的第一个要点 - 这里是第二个要点这里的---不是普通的分隔线而是一页的内容结束、下一页内容开始的位置。如果没有这个分隔线整个文件会被当作一页幻灯片。这也是 AI 生成草稿时最容易出错的地方模型有时会在文档中间插入普通分隔线导致渲染结果出现多余的空白页或分页错乱。理解了分页机制再看 Markdown 幻灯片的其他写法就会觉得非常自然#或##表示页内标题-表示要点表格和代码块也可以直接放进页面里。等到渲染时主题会把这些内容按一定的视觉规则排版到一张固定尺寸的画布上。1.2 主流的 Markdown 幻灯片方案对比虽然写法都类似但不同工具在分页、主题、导出、交互能力上差别很大。选择工具前先看一张对比表工具分页方式运行方式典型导出能力适合场景Marp---分页支持 front matterVS Code 插件或 CLIPDF、HTML、PPTX快速编写、课堂演示、文档交付Slidev---分页支持 Vue 组件Vite 开发服务器浏览器访问PDF、PPTX、PNG需要代码高亮和复杂交互的演讲Reveal.jsHTML 或 Markdown 子集静态页面浏览器展示PDF通过浏览器打印Web 端自主控制页面动画md-to-pdf普通 Markdown 分页、分节Node.js 脚本PDF、HTML文档转 PDF适合报告型内容Pandoc传统 Markdown 文档命令行转换PDF、PPTX、HTML从长文档转成简单幻灯片选择时优先考虑两件事第一分页是否通过---实现这决定 AI 提示词是否容易生成第二导出是否依赖本地浏览器或独立渲染内核这决定 CI 构建的复杂度。学习环境里Marp 因为“VS Code 插件 CLI”都齐全成本最低。团队协作或复杂前端演示场景Slidev 更合适。1.3 AI 在幻灯片工作流里的合理位置AI 辅助写幻灯片并不等于让模型把一整套 PPT 都生成完。实际工作中模型的价值在三个任务上最明显根据主题生成大纲和每一页的标题减少从零搭建逻辑的投入。把长段落改写成适合演示的短句和要点避免照搬文档。生成页面的演讲备注、过渡语、案例帮助演讲者真正讲出内容而不只是念标题。AI 不擅长的是决定字号、配色、页面节奏。视觉问题最好交给主题和手工调整。因此在整条工作流里AI 负责“内容生产”人负责“内容质量和表现控制”。这样分工清晰效率和可控性可以兼顾。2. 先搭一个最小可运行环境VS Code Marp为了让后面的步骤可验证先搭一个最小环境。这里选择 Marp 作为示例因为它的依赖最少安装方式也有多条路径。2.1 环境准备和安装本地环境需要以下三样东西Node.js建议使用 LTS 版本用于运行 Marp CLIVS Code可选但装插件后预览体验最好一个终端工具安装 Marp CLI 有两种方式。一种是全局安装npm install -g marp-team/marp-cli另一种是项目内安装方便锁定版本、进入 CImkdir ai-slides-demo cd ai-slides-demo npm init -y npm install -D marp-team/marp-cli如果使用 VS Code建议同时安装 Marp for VS Code 扩展。安装后打开 Markdown 文件点击右上角的预览按钮就能进入幻灯片预览模式。这个模式对验证分隔符和字号非常有用。2.2 写一个最小示例文件在项目目录下创建slides.md内容如下--- theme: default paginate: true size: 16:9 --- # 用 Markdown 写幻灯片 这是一个最小示例。 --- ## AI 在这里做什么 - 生成大纲 - 优化要点 - 翻译讲稿保存文件后如果安装了 Marp 插件点击“预览”即可看到两页幻灯片。第一页是大标题第二页是标题加三条要点。此时整个链路已经跑通。2.3 验证最小项目是否成功验证一个 Markdown 幻灯片项目不只是看“能不能渲染出页面”还需要确认几个关键点页面数量是否正确。默认情况下一个---代表页与页之间的切换页面数量等于---数量加一。front matter 是否生效。theme、size、paginate这些配置需要出现在文件开头并且用---包裹。预览窗口是否按宽高比显示。如果size: 16:9没有生效检查是不是 front matter 写错了位置。如果页面数量不对优先检查文件末尾是否多了一个---以及---前后是否有空行。在 Marp 中分页符通常需要前后空行否则可能被解析成普通分隔线。3. 让 AI 生成幻灯片草稿提示词模板和修正方法环境就绪后可以进入 AI 辅助内容生成环节。直接对模型说“帮我写一个 PPT”通常得到的是很难直接用的长文。更稳妥的做法是给模型提供明确的结构约束让它输出“接近 Marp 语法”的 Markdown。3.1 为什么不能只依赖 AI 的一次性输出大语言模型生成 Markdown 幻灯片时容易出现几个典型问题输出整段长文而不是短句要点。使用#表示整篇文章的章节而不是一页的标题。把整个 Markdown 内容包裹在一个大的代码块里导致渲染不出来。分页符使用不统一有时候是---有时候是三个以上的连字符。这些问题不会因为更换模型而彻底消失。所以在工作流中AI 输出只是“草稿”必须经过一次“结构修正”后才进入渲染环节。可以把修正逻辑写成固定步骤每次都用同一套规则减少人工判断成本。3.2 生成幻灯片草稿的提示词模板下面是一个适合 Marp 的提示词模板。关键信息包括主题、页数、听众、时长、演示重点、输出格式。请把我的主题做成一组 Markdown 幻灯片要求如下 主题可观测性系统的落地实践 页数10 听众后端开发和运维同学 时长15 分钟 演示目标让听众理解为什么需要可观测性以及实践时优先做哪三件事 输出要求 - 使用 Marp 语法 - 每一页之间用 --- 分隔 - 页面标题使用 #副标题或内容使用 ## 或列表 - 第一页是封面最后一页是结论 - 每页要点控制在 4 条以内 - 需要代码示例的页面用 代码块括起来 - 不要输出汇总说明直接输出完整 Markdown这条提示词增加了三个关键约束页数、内容密度、输出格式。模型返回结果后还需要检查是否满足这些约束而不是直接复制到slides.md。3.3 示例把 AI 草稿修正成可渲染版本假设模型返回了这样一段内容# 可观测性系统的落地实践 主讲人张三 ## 什么是可观测性 可观测性是指可以从外部输出推断系统内部状态的能力。它由日志、指标、链路追踪三个部分组成。 - 日志记录事件 - 指标记录数据 - 链路追踪记录请求路径从内容上看这段描述没有问题但它并不完全适合幻灯片。需要修正成更短的要点# 可观测性系统的落地实践 主讲人张三 --- ## 什么是可观测性 - 从外部输出推断内部状态的能力 - 三大支柱日志、指标、链路追踪 - 目标是快速定位“哪里出了问题”修正时重点做三件事把长句拆成短句把每页内容压缩到 3 到 4 条确认每页之间已经用---隔开。完成后再进入预览环节页面效果会明显更清晰。4. 用 AI 把草稿完善成可演示内容语法、备注和内容密度AI 生成好初稿后下一步是把文本转换成真正适合演示的页面。这里涉及 Marp 的语法细节也涉及内容质量控制。4.1 用 front matter 控制主题和页面参数Marp 文件开头的---区域是配置区。常见配置如下参数作用常用值theme页面主题default、gaia、uncover、自定义主题size宽高比16:9、4:3paginate是否显示页码true / falsebackgroundColor背景色#FFFFFF、#1E1E1Ecolor正文字色#333333、#FFFFFFheader每一页顶部固定内容相对固定的章节名footer每一页底部固定内容作者、会议名称一个适合演讲的示例配置--- theme: gaia size: 16:9 paginate: true backgroundColor: #FFFFFF color: #222222 ---这里要注意theme决定整体视觉风格size决定输出尺寸。如果页面上有大量代码块可以考虑backgroundColor使用深色配合代码高亮主题。4.2 让内容更适合投影列表、代码块、图片和公式演示场景下文字越少越好。常见的做法是把一段描述改成列表## 三条核心结论 - 先做链路追踪再补指标 - 日志结构化是前提 - 告警必须可回溯代码块可以直接放进页面中## 核心示例 go func main() { fmt.Println(hello) } 图片可以通过 Markdown 标准语法引入如果展示数学公式Marp 支持 LaTeX 语法无论是 $Emc^2$ 还是块级公式都可以直接渲染。这里有个容易被忽略的问题不要把一页塞满五六个要点、两段代码和一张大图。幻灯片是辅助讲解的不是文档拷贝。建议每页只保留一个核心主题、三到四行要点、一个示例块。4.3 利用演讲备注承载讲稿正式演示时页面上只放关键词但演讲者仍需要完整的讲稿。Marp 允许在页面中写入备注## 为什么需要链路追踪 - 定位慢请求 - 还原调用关系 !-- note: 这里可以先讲一个线上故障案例再引出链路追踪的价值。讲完案例后再强调数据采样和存储成本。 --这段备注在预览和导出 PDF 时不会显示但在演讲者模式下可以看到。AI 也可以生成这部分内容。提示词可以单独补充请为以下幻灯片内容写演讲备注要求 100 字左右包含一个开场案例和一个过渡句。通过备注把“页面内容”和“演讲词”分开是 Markdown 幻灯片明显优于传统 PPT 的一点。因为讲稿不再需要单独维护一份 Word 文档可以直接和页面内容放在同一个 Markdown 文件里。5. 本地预览、导出 PDF/HTML/PPTX以及自动化构建内容完成后最重要的动作是验证和交付。Marp 提供的预览和导出能力能够覆盖常见使用场景。5.1 本地预览的三种方式第一种方式是 VS Code 插件预览。优点是所见即所得缺点是依赖编辑器环境。第二种方式是 CLI 启动监听npx marp-team/marp-cli slides.md -w --html-w表示监听文件变化--html允许页面中包含 HTML 代码。第三种方式是构建静态站点到本地目录npx marp-team/marp-cli slides.md -o dist/index.html推荐在写完每一页后都进入预览看一眼。尤其是确认分页是否正确、标题层级是否平滑、代码块是否溢出了页面。5.2 导出 PDF、HTML 和 PPTX导出 PDF 最常用npx marp-team/marp-cli slides.md --pdf导出 HTML 可以通过前面提到的-o dist/index.html完成。HTML 版比 PDF 更灵活可以在浏览器里播放也方便嵌入到企业内网。导出 PPTX 需要额外的渲染依赖npx marp-team/marp-cli slides.md --pptxPPTX 导出依赖浏览器内核首次运行可能会自动下载 Chromium。如果下载失败需要检查网络环境和本机权限。导出后还要打开 PPTX 检查中文字体是否正常因为部分主题内置的字体映射和多语言处理并不完善。5.3 用 CI 自动生成发布包如果团队需要定期发布演示文稿可以把构建放到 CI 中。以 GitHub Actions 为例只需要一个相对简单的任务在推送时安装 Node.js安装 Marp CLI然后执行导出命令。name: build-slides on: push: branches: [main] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 20 - run: npm ci - run: npx marp-team/marp-cli slides.md --pdf - uses: actions/upload-artifactv4 with: name: slides path: slides.pdf这个示例说明了思路。实际项目中要根据仓库结构、包管理器、是否使用自定义主题来调整。进入 CI 前先确认本地已经能够顺畅导出否则 CI 只是把你的环境问题复制到远端。6. AI 提示词复用手册从生成到优化再到备注AI 在 Markdown 幻灯片工作流中能承担很多角色。只要把提示词拆成固定的小模板就可以在每次做演示时复用同一套逻辑。6.1 常用提示词模板下面按任务分类列出几个模板。任务一从空白主题生成大纲请为《主题名称》设计一个 6 页的演示文稿大纲。 每页只写标题和核心要点不要展开成段落。 输出格式每页标题用 #要点用 -。任务二把长文改写成幻灯片要点下面是《主题名称》的一段介绍材料。 请改写成适合演讲的 4 个短句要点。 每句话不超过 20 个字不要使用复杂术语。任务三生成演讲备注请为上面这页内容写演讲备注要求 100 字左右包含一句话开场和一句过渡。任务四精简过密的页面这页内容太多请压缩到 4 行要点并保持信息不丢失。任务五统一分页符请把正文中所有可能出现混淆的 --- 分隔符保留只用于幻灯片分页。 不要添加多余的横线。6.2 提示词里的可变参数为了让提示词在不同场合复用可以把关键变量单独提出来主题、页数、听众、时长、演示目标、输出格式。凡是容易变化的点都放进提示词里明确写出来这样模型不会用自己的假设补充。变量示例影响主题可观测性落地实践决定内容来源页数10决定交付规模听众后端开发决定术语深度时长15 分钟决定每页内容量输出格式Marp Markdown决定能否直接渲染6.3 把 AI 辅助嵌入编辑器流程如果不想每次都在对话框里复制粘贴可以把提示词集中写在一个文件里。例如在项目根目录维护prompt.md使用 VS Code 的 Copilot Chat 或类似工具时直接用/slides这样的自定义指令引用模板。也可以写一个简单的 Node.js 脚本从命令行传入主题和页数再调用模型接口生成 Markdown 文件。不过要提醒一点生成脚本只是帮你产出初稿最终文件仍然要经过人工 review。项目里建议新增一条规矩AI 生成的 Markdown 必须通过本地预览验证后才能提交到 Git 仓库。这样可以避免把分页符错误或格式问题带到 CI 中。7. 常见问题与排查路径在实际使用中Markdown 幻灯片项目一旦失败多数问题集中在格式、依赖和渲染环境三类。下面从现象出发给出排查顺序。7.1 问题现象和处理方案速查表问题现象常见原因检查方式处理建议页面数量比预期少---前没有空行被当作普通分隔线查看原始文件中的分页符前后是否都有空行统一在---前后保留空行页面数量比预期多文档中出现了多余的---搜索文件中所有---确认每一处都是分页删除多余分隔线AI 生成的 Markdown 全部显示为一页模型把整个内容放在了一个代码块里检查内容是否被包裹去除最外层代码块再手动格式化图片显示为裂图图片路径相对当前目录不对检查![]()中的路径和文件名使用相对路径并确认图片文件存在导出 PDF 时中文字体异常主题缺少中文字体映射对比 HTML 预览和 PDF 输出切换主题或指定系统字体PPTX 导出失败缺少 Chromium 或权限不足查看终端错误日志手动安装依赖或改为导出 HTML代码块溢出页面代码行过长预览模式下观察右侧是否超出减少代码行使用更小字号或横向滚动front matter 配置不生效配置区写错位置检查---是否位于文件首行确认---和配置之间没有多余内容7.2 从现象倒推原因排查链路遇到问题时按下面的顺序排查能减少浪费在猜测上的时间。先看原始文件。确认文件扩展名是.md分页符前后是否有空行front matter 是否位于第一行。再看预览方式。VS Code 插件预览和 CLI 渲染有时行为不同。如果插件预览正常但 CLI 导出失败问题很可能在依赖环境。再查版本。运行npx marp-team/marp-cli --version或查看 VS Code 扩展版本确认与 README 中的示例一致。再查日志。CLI 导出失败时终端会输出错误信息先搜错误关键字再搜索解决方案。最后检查外部依赖。PPTX 导出需要浏览器内核PDF 导出如果使用自定义字体还要确认字体文件和系统权限。7.3 三个容易踩的坑第一个坑AI 生成内容时把 Markdown 的“普通分隔线”和“分页符”混在一起。文章里常见的---会被解释为分页导致页面数量激增。解决方案是在提示词中明确指出“所有---只用于分页”并在修正阶段把所有非分页用途的---删除。第二个坑AI 输出了多层嵌套的 Markdown 代码块。模型为了展示“这是一段 Markdown 文本”会把整个幻灯片内容包在外层代码块中。复制到.md文件后编辑器只会显示一个代码块不会渲染成幻灯片。解决方案是识别最外层代码块并去掉。第三个坑一页内容过密。Markdown 没有“文本框尺寸”的概念所以很容易在不知不觉中塞入大量内容。演示时投影屏幕又比普通显示器小最终效果就是字号被压缩到看不清。解决方案是建立页面内容密度检查每页不超过 4 个要点不超过 10 行文本代码块只保留核心片段。8. 学习环境与生产环境的差异以及可复用检查清单在最后一部分把学习阶段和团队交付阶段的差异讲清楚。这样你既能快速上手做一场分享也能在正式项目中避免返工。8.1 学习环境建议和生产环境建议学习阶段的目标是快速跑通链路。最简单的是“VS Code Marp 插件 本地 PDF 导出”。你只需要一个编辑器和一个.md文件就能完成大部分练习。进入团队协作或正式发布阶段建议做三件事在项目仓库里固定 Marp CLI 版本避免不同机器渲染结果不一致。把自定义主题、logo、字体放到独立目录成为可复用的资源包。将导出流程接入 CI让每次提交都生成一份可下载的 PDF 或站点。如果是复杂产品演示需要动画、路由、嵌入组件再考虑迁移到 Slidev因为它基于 Vue/Vite可以承载更复杂的页面交互。但不要从一开始就引入这些复杂度先用 Marp 把内容和流程跑顺再根据实际需要升级。8.2 常用参数选型表做幻灯片时参数不需要多但每个都要知道影响什么。参数推荐值影响调大后的结果调小后的结果size16:9页面宽高比横向空间更多接近方形paginatetrue是否显示页码方便听众定位页面更干净内容密度3-4 个要点/页阅读负担信息量更大但难读清晰但翻页变多footer作者或会议名品牌信息更正式页面更简洁font-size不设置或用主题默认可读性适合大屏适合代码块较多生产环境建议把size、paginate、footer放到 front matter 中统一控制不要在每个页面里写死。这样后续改样式只改一处即可。8.3 发布前检查清单每次把 Markdown 幻灯片交付给他人前建议逐项检查以下内容Markdown 文件在本地能否成功预览。分页数量是否符合预期没有多余---。每一页标题层级保持一致没有从#直接跳到###。所有图片路径都能正常加载。代码块没有被误渲染成文本也没有溢出页面。PDF 或 PPTX 导出后中文和代码高亮正常。演讲备注中的重要数据、案例、时间点没有过时。页面内容密度合理每页不超过 4 个要点。如果给外部听众演示确认没有内部链接和敏感信息。如果通过 CI 构建确认构建产物已经成功上传到指定位置。这套清单可以在每次发布前复用。Markdown 幻灯片的优势是内容容易审阅但正因为内容都在一个文件里格式问题也会被快速放大。保持“先预览再导出后发布”的顺序就能把体验稳定控制住。把 Markdown 和 AI 结合起来做幻灯片最大的价值不是省掉所有排版动作而是把内容生产、结构整理、讲稿准备的过程压缩成一条可以重复使用的流程。你只需要给出主题AI 负责生成素材Markdown 负责承载结构Marp 负责渲染和导出最后由你来把握质量和节奏。真正上手时先从一个 5 页的小案例开始跑通预览、备注、导出三个动作再逐步加入主题、自动化构建和复杂的演讲场景。这样学得最快也最不容易在前期就被工具链的细节卡住。