每次做技术分享 PPT最耗时间的往往不是思路而是调整版式标题字号、图片位置、分页节奏、字体统一改完内容又得重排一遍。后来接触了用 Markdown 写幻灯片的工作流配合 AI 生成初稿整个流程被大幅压缩。本文会把这套“Markdown AI 幻灯片”做法完整拆开从原理讲到能直接使用的工程化方案。文章适合以下几类读者经常做技术分享、组内汇报的开发者想用纯文本管理演示文稿、不想被 PPT 软件绑定的人正在调研 Markdown 编辑器、Markdown 渲染方案想了解 AI 大模型如何参与内容生产的人。读完本文你可以掌握 Marp 的核心写法学会用 AI 批量生成幻灯片初稿并完成 PDF、PPTX、HTML 多种格式的导出和发布。1. 用 Markdown 做幻灯片的原理与价值1.1 Markdown 幻灯片本质是“内容与样式分离”传统 PPT 的本质是“画布 对象”。每一页的内容、位置、大小、动画都保存在同一个文件里。这种模型的好处是所见即所得坏处是内容调整和样式调整耦合在一起后续维护成本很高。Markdown 幻灯片换了一种思路内容用纯文本描述渲染时再套用统一样式。你只需要写标题、正文、列表、代码、图片引用剩下的排版交给渲染引擎完成。这样内容文件小、容易做版本管理、也方便被程序批量处理。以 Marp 为例一份最简幻灯片长这样--- marp: true --- # 第一页标题 - 要点一 - 要点二不需要拖拽画布不需要设置字号渲染引擎会自动按主题排版。1.2 AI 在幻灯片工作流中做什么AI 大模型的强项是文本生成与结构化改写正好对应幻灯片制作中最耗时的部分生成大纲给定主题先生成章节结构展开单页内容把大纲扩写成每页要点改写润色把复杂段落压缩成适合演示的短句生成演讲备注为每页生成口语化的讲稿统一语气风格让不同来源的材料合并后风格一致。AI 负责“写什么”Markdown 负责“怎么排版”。两者结合后制作一套 20 页左右的技术分享幻灯片时间可以从几小时压缩到几十分钟。1.3 常见 Markdown 幻灯片工具目前常用的方案主要有三类工具特点适合场景Marp语法简单直接从 Markdown 生成幻灯片支持 VS Code 插件快速入门、技术分享、日常汇报Slidev基于 Vue支持主题、代码高亮、图标、动画扩展能力强对视觉效果要求较高的技术人员Reveal.js老牌 HTML 演示框架Markdown 是其一种内容格式深度定制网页演示本文主角是 Marp因为学习成本最低与 AI 结合最直接也是目前“Markdown 幻灯片”搜索关注度最高的方案之一。2. 环境准备与工具安装2.1 环境要求Marp 本身不依赖特定操作系统Windows、macOS、Linux 都能用。我们在本文中的示例基于常见环境操作版本相关细节请以你实际安装时的 release 信息为准。准备工具清单Node.js 18 或以上版本Marp CLI 依赖 Node 环境一个现代浏览器用于预览 HTML 导出结果文本编辑器推荐 VS Code配合 Markdown 插件使用体验更好Python 3.9用于后续 AI 调用示例脚本。如果你不熟悉 Node.js 安装可以访问 Node.js 官方网站下载 LTS 版本。2.2 安装 Marp CLIMarp 官方提供了命令行工具marp-team/marp-cli推荐全局安装npm install -g marp-team/marp-cli安装完成后验证版本marp --version如果终端能输出版本号说明安装成功。这里要提醒一点Marp CLI 更新比较频繁不同版本的参数有小幅差异执行marp --help可以查看当前帮助信息。2.3 安装 VS Code 插件可选如果你习惯在 VS Code 中编辑 Markdown可以安装官方插件插件名称Marp for VS Code安装方式在 VS Code 扩展面板搜索Marp找到marp-team.marp-vscode安装即可安装后打开.md文件如果文件头部 YAML 配置中有marp: true编辑器右上角会出现预览按钮点击即可实时查看幻灯片效果。2.4 准备 AI 调用环境后面实战会用一个 Python 脚本调用大模型 API。为了不绑定具体厂商示例代码使用 OpenAI 兼容接口风格你需要准备一个可用的 API Key服务商提供的接口地址 base_url你选择的模型名称。按照最小权限原则建议把 API Key 放在环境变量中不要写进代码文件也不要提交到 Git 仓库。# Linux / macOS export LLM_API_KEY你的API密钥 export LLM_BASE_URLhttps://api.example.com/v1 # Windows PowerShell $env:LLM_API_KEY你的API密钥 $env:LLM_BASE_URLhttps://api.example.com/v1这里LLM_BASE_URL只是示例占位请替换成你实际使用服务商提供的地址。3. Marp 核心语法详解Mar 的本质是 Markdown 超集。它在标准 Markdown 的基础上增加了---分页符和 YAML frontmatter 配置。下面按难度拆开讲解。3.1 YAML frontmatter控制全局设置Markdown 文件开头可以写一段由---包裹的 YAML 配置Marp 会读取这段配置作为全局设置。--- marp: true theme: gaia paginate: true size: 16:9 ---常用配置说明marp: true启用 Marp 渲染没有该配置时文件会被当成普通 Markdowntheme幻灯片主题内置default、gaia、uncover三种paginate是否在每页底部显示页码size幻灯片尺寸常见有16:9和4:3class自定义 CSS 类用于配合自定义主题文件backgroundImage全局背景图header/footer全局页眉页脚文字。3.2---分页符在 Marp 中三个连字符---独占一行表示一张幻灯片结束、下一张开始。--- marp: true --- # 第 1 页 这是第一页内容。 --- # 第 2 页 这是第二页内容。注意开头的 YAML frontmatter 也是用---包裹的但位于文件最顶部Marp 会把它解析为配置而不是一个分页符。3.3 内容排版常用写法在幻灯片内你可以使用大部分标准 Markdown 语法标题#到######列表-无序列表、1.有序列表引用;代码反引号包裹的单行代码或三反引号包裹的代码块表格管道符绘制的 Markdown 表格图片。除此之外Marp 还提供了一些页面内指令。1. 背景图片![bg]会让图片铺满整张幻灯片作为背景。也可以指定位置此时背景图位于左侧右侧留出空间放文字内容。2. 多列布局Marp 内置了一些 CSS 类可以实现两栏布局div classcolumns div 左侧内容Markdown 也支持。 /div div 右侧内容。 /div /div3. 数学公式使用$或$$包裹 LaTeX 公式行内公式 $Emc^2$。 独占一行 $$ \sum_{i1}^{n} i \frac{n(n1)}{2} $$4. 高级代码主题Marp 代码块高亮基于 Highlight.js支持常见的语言标注python def hello(): print(Hello Marp)### 3.4 自定义主题 如果内置主题不满足视觉要求可以在 themes 目录中放一个 CSS 文件然后在 frontmatter 中声明主题路径。例如目录结构如下slides/ ├── themes/ │ └── my-theme.css └── deck.mddeck.md 头部配置 yaml --- marp: true theme: my-theme ---Marp 会优先从当前目录的themes文件夹查找同名 CSS 文件。自定义 CSS 的例子/* themes/my-theme.css */ section { background: #f8f9fa; color: #2d3436; font-family: Noto Sans SC, Microsoft YaHei, sans-serif; } section h1 { font-size: 48px; color: #0984e3; border-bottom: 3px solid #0984e3; padding-bottom: 12px; }小结一下Marp 的语法并没有改变 Markdown 的表达能力而是在“分页”和“全局样式”上做了增强。你学习时不需要死记硬背把 frontmatter 配置、---分页、背景图、主题 CSS 这四块理解清楚就能覆盖绝大多数场景。4. 完整实战用 AI 生成一套 Markdown 幻灯片下面我们做一个完整项目AI 根据主题生成 Marp 格式的 Markdown 幻灯片然后用 Marp CLI 导出多种格式。4.1 项目整体结构先规划一个清晰的目录结构便于管理和版本控制。markdown-ai-slides/ ├── scripts/ │ └── generate_slides.py ├── slides/ │ └── tech-share.md ├── output/ │ ├── tech-share.html │ ├── tech-share.pdf │ └── tech-share.pptx └── requirements.txtscripts存放 AI 调用脚本slides存放生成的 Markdown 源文件output存放导出文件requirements.txtPython 依赖。4.2 Python 依赖准备使用 Python 调用大模型接口最低要求是安装openaiSDK。如果使用其他兼容接口依赖包名称可能不同请以服务商文档为准。pip install openairequirements.txtopenai1.0.04.3 编写 AI 生成脚本创建一个scripts/generate_slides.py文件思路如下从环境变量读取 API Key 和 base_url构造 Prompt要求模型按 Marp 语法输出幻灯片 Markdown把模型返回内容写入slides/tech-share.md打印文件路径和字符数方便确认结果。示例代码# 文件路径scripts/generate_slides.py import os from pathlib import Path from openai import OpenAI # 从环境变量读取配置避免把密钥写进代码 api_key os.environ.get(LLM_API_KEY) base_url os.environ.get(LLM_BASE_URL) if not api_key or not base_url: raise ValueError(请先设置 LLM_API_KEY 和 LLM_BASE_URL 环境变量) client OpenAI(api_keyapi_key, base_urlbase_url) PROMPT 请帮我生成一份关于“用 Markdown 与 AI 制作幻灯片”的演示文稿。 要求 1. 使用 Marp 语法文件头部必须包含 YAML frontmattermarp: true, theme: gaia, paginate: true。 2. 页与页之间使用单独的 --- 分隔。 3. 总页数 10 到 15 页。 4. 每页内容控制在 5 个要点以内表达简洁。 5. 至少包含一页代码示例、一页表格。 6. 只输出 Marp Markdown 源码不要输出解释性文字。 if __name__ __main__: response client.chat.completions.create( model你的模型名称, # 请替换为实际模型 messages[ {role: system, content: 你是一个擅长结构化表达的技术文档作者。}, {role: user, content: PROMPT}, ], temperature0.7, ) content response.choices[0].message.content output_dir Path(__file__).resolve().parent.parent / slides output_dir.mkdir(exist_okTrue) output_path output_dir / tech-share.md output_path.write_text(content.strip(), encodingutf-8) print(f已生成: {output_path}) print(f字符数: {len(content)})这段代码里的model、base_url必须和你实际使用的大模型服务保持一致。如果你使用的是本地模型兼容 OpenAI 接口同样可以用这套写法。安全提醒不要在脚本里硬编码 API Key脚本本身也不要提交包含敏感信息的版本到公开仓库。4.4 运行生成脚本确认环境变量设置完成后执行cd markdown-ai-slides python scripts/generate_slides.py预期输出已生成: .../markdown-ai-slides/slides/tech-share.md 字符数: 2368生成的内容是纯文本 Markdown可能格式会因模型输出略有差异。打开文件检查一下 frontmatter 和分页符是否完整。4.5 使用 Marp 预览与编辑用 VS Code 打开slides/tech-share.md如果安装了 Marp 插件点击右上角预览按钮即可看到 HTML 渲染效果。也可以使用 CLI 启动本地预览marp -w slides/tech-share.md-w表示 watch 模式文件每次保存都会自动重新渲染浏览器打开 http://localhost:8080 即可实时预览。4.6 导出 HTML、PDF、PPTXMarp CLI 支持把 Markdown 转成多种格式。导出 HTMLmarp slides/tech-share.md -o output/tech-share.htmlHTML 文件是自包含的可以直接发给别人打开也可以部署到静态服务器。导出 PDFmarp slides/tech-share.md --pdf -o output/tech-share.pdf实际上Marp 导出 PDF 的原理是启动一个无头 Chromium 浏览器渲染页面所以如果你本机缺少相关依赖首次运行可能会提示安装。这时候按提示安装缺失组件即可。导出 PPTXmarp slides/tech-share.md --pptx -o output/tech-share.pptx需要特别说明的是PPTX 导出采用“将每页渲染成图片再放入 PPT”的方式。这样能最大程度保留视觉样式但导出的 PPT 文件不是可编辑的原生形状对象。如果需要拿给不熟悉 Marp 的同事二次编辑这个限制要提前沟通好。如果你的演示文稿有自定义背景图或复杂 CSS 特效导出 PDF 通常比 PPTX 更稳定。4.7 验证输出结构生成完成后slides/tech-share.md应该具备类似结构。为了演示下面给出一段手工编写的 Marp 源码片段你可以对照检查生成的 Markdown 是否符合预期--- marp: true theme: gaia paginate: true --- # 用 Markdown 与 AI 制作幻灯片 分享人你的名字 日期2025 年某月 --- ## 为什么选择 Markdown - 纯文本易维护 - 支持 Git 版本管理 - 内容与样式分离 - 方便 AI 批量生成如果 AI 生成的格式有偏差优先检查三点文件开头是否有marp: true分页符是否是独立的一行---标题层级是否连续不要从#直接跳到####。5. 常见问题与排查思路5.1 生成的 Markdown 无法正确分页现象所有内容挤在一页幻灯片里。原因文件里的分页符不是单独的---或者---前面没有空行被 Markdown 解析成了 setext 标题或普通横线。解决思路打开文件确认分页符单独占一行前后各有一个空行检查是否误用***或___Marp 分页只识别---如果 AI 输出内容中没有分页符可以在 Prompt 中明确强调“页与页之间使用独立的 --- 分隔”。5.2 AI 生成的 YAML 头部缺失现象文件看起来是 Markdown但 Marp 预览不生效主题、页码都没有。原因模型可能漏掉了 frontmatter或者 frontmatter 的键值对写错了缩进。解决思路手写一个最小 frontmatter 塞到文件开头--- marp: true theme: default paginate: true ---如果 AI 输出经常漏配建议 Prompt 中直接给一个模板片段让它基于模板填充而不是从零生成。5.3 本地图片无法显示现象代码中的图片地址为相对路径时预览页面显示裂图。原因Marp 渲染时的工作目录与图片相对路径不一致或图片文件名包含中文/空格导致 URL 解析问题。解决思路尽量使用英文文件名使用相对slides目录的路径例如如果图片不多可以转成 Base64 后嵌进 Markdown保证文件可独立分发网络图片地址要确认可访问不要依赖公司内网图床做对外分享。5.4 导出 PDF 时字体异常、中文变成方块现象PDF 里中文显示为方框或乱码。原因系统缺少中文字体或 Marp 渲染时未能正确指定字体。解决思路在自定义主题 CSS 中指定常见中文字体例如Noto Sans SC、Microsoft YaHei、PingFang SC导出 PDF 前先安装系统级中文字体包先确认 HTML 预览正常再导出 PDFHTML 正常说明字体问题大概率出在系统层。5.5 生成的 PPTX 文字不可编辑现象用 PowerPoint 打开导出文件发现选中文字只能当图片整块移动无法改字号。原因Marp 的 PPTX 导出是基于每页截图实现的不是可编辑矢量对象。解决思路如果需要原生可编辑 PPTMarp 不适合建议换用 Slidev 或其他支持原生 PPT 导出的工具如果只是给他人只读查阅PDF 文件更方便打印和分发。问题现象常见原因解决思路所有内容在一页分页符格式错误检查---是否独立一行主题配置不生效YAML frontmatter 缺失在文件头部补充配置本地图片裂图路径或文件名问题使用英文文件名和相对路径PDF 中文乱码中文字体缺失安装字体并指定字体栈PPTX 不可编辑按图片导出必要时使用 PDF 或原生工具6. AI 与 Markdown 幻灯片结合的进阶用法6.1 设计稳定的 Prompt 模板AI 生成幻灯片质量的下限取决于 Prompt 质量。推荐把 Prompt 结构化拆分角色你是一个擅长结构化表达的技术文档作者。 任务生成 Marp 格式的演示文稿 Markdown。 主题xxx 页数10-15 页 面向人群后端开发工程师 每页结构标题 3-5 个要点 风格简洁、技术化 格式要求YAML frontmatter 使用 marp: true页之间用 --- 分隔不要输出解释性文字。Prompt 越具体Markdown 越规范。建议把这段模板保存在prompts/slide_prompt.md方便后续复用和迭代。6.2 分步生成先大纲后细节一次性让模型生成 20 页完整内容容易出现逻辑重复或内容空洞。更稳妥的做法是两阶段生成。阶段一让模型生成大纲。请为主题“xxx”生成一份 15 页技术分享的目录结构每页给出标题和一句话说明用 Markdown 列表输出。阶段二让模型逐页展开内容。针对下面这一页标题编写内容 标题xxx 要求4 个要点每个要点不超过 20 字使用 Marp 列表语法。分步生成降低了每次请求的复杂度也让 AI 输出更稳定。生成的片段再拼接成完整文件即可。6.3 用 AI 做演讲备注幻灯片内容要简洁但演讲者需要口语化讲稿。可以让 AI 为每页生成备注Marp 导出 PPTX 时备注不会直接体现在画布上但对演讲准备很有帮助。示例 Prompt请为以下幻灯片内容生成演讲备注要求自然口语化时长约 1 分钟不要使用书面语。 内容 ### 为什么选择 Markdown - 纯文本易维护 - 支持 Git 版本管理6.4 批量制作多套幻灯片如果企业内经常需要生成固定模板的分享材料可以写一个批处理脚本把主题列表作为参数循环调用 AI再把生成结果汇总成多个文件。topics [ 微服务拆分的十个问题, MySQL 索引优化实践, 前端工程化落地经验, ] for topic in topics: slide generate_slide(topic) save_to_file(topic, slide)这个思路也适合产品说明书、培训材料、技术周报等场景一套脚本覆盖多类内容。7. 最佳实践与工程建议把“Markdown AI”这套流程用到生产环境时有几个容易被忽略但实际影响很大的点。7.1 把幻灯片当成代码来管理Markdown 是纯文本天然适合放进 Git。建议按照“一个分享主题一个目录”来组织目录内包含slides.md幻灯片源码images/图片素材themes/主题 CSSprompts/AI 提示词模板scripts/生成脚本。这样团队协作时改幻灯片可以走代码评审流程能追溯每一轮改动是谁提交的。长期维护多套幻灯片时这种管理方式的价值会非常明显。7.2 注意内容安全与数据隐私使用 AI 生成幻灯片时一定要控制输入内容边界。公司内部的业务数据、用户隐私、未公开的架构设计不要直接塞进 Prompt 发送给外部模型服务。建议遵循最小权限原则涉及敏感数据的内容不要走外部 AI 服务如确实需要使用支持私有部署的模型服务API Key 通过环境变量注入不要硬编码定期轮换密钥避免密钥泄露后影响范围扩大。7.3 控制单页信息量幻灯片每一页表达一个核心观点最多 5 个要点。AI 生成内容容易写得“满”人工审稿时建议做减法一句标题能说完就不要拆成三段代码只保留关键部分不要整页铺代码图表优先于大段文字演讲备注承载细节幻灯片只留主结构。这样既符合技术分享的观察体验也降低后续排版调整的工作量。7.4 自定义主题模板团队内可以沉淀一套标准主题 CSS把字号、配色、页脚、Logo 统一起来。以后任何人做分享只需要复制主题文件内容简单写视觉依然统一。例如themes/company-style.css中定义主色调、标题字重、页脚展示/* themes/company-style.css */ section::after { content: attr(data-marpit-pagination) / attr(data-marpit-pagination-total); position: absolute; bottom: 16px; right: 24px; font-size: 12px; color: #888; }运行时在 frontmatter 中声明--- marp: true theme: company-style ---7.5 先确认输出格式再做自动化部分团队希望把自动生成的 Markdown 直接转成 PPTX 再交付给业务方。建议先给业务方演示 PDF 和 PPTX 两种版本确认对“可编辑性”要求后再决定导出策略。否则做了大量自动化最后发现对方需要原生可编辑 PPT返工成本很高。8. 结语用 Markdown 做幻灯片核心是解决传统 PPT“内容与样式耦合”的问题引入 AI 之后又把“从空白页开始写文案”这个瓶颈大幅降了下来。建议你先从一次小范围的技术分享开始把 Marp 的语法跑顺再逐步加入 Prompt 模板、自定义主题和批量生成脚本。如果本文对你有帮助可以收藏备用。下一篇可以继续聊聊如何把这份 Markdown 幻灯片接入团队知识库或者用自定义主题统一多场分享的视觉风格。 
长河君 · 2026/9/3 11:17:49 · 阅读 1.2k 用 Markdown + AI 高效制作技术分享幻灯片指南
每次做技术分享 PPT最耗时间的往往不是思路而是调整版式标题字号、图片位置、分页节奏、字体统一改完内容又得重排一遍。后来接触了用 Markdown 写幻灯片的工作流配合 AI 生成初稿整个流程被大幅压缩。本文会把这套“Markdown AI 幻灯片”做法完整拆开从原理讲到能直接使用的工程化方案。文章适合以下几类读者经常做技术分享、组内汇报的开发者想用纯文本管理演示文稿、不想被 PPT 软件绑定的人正在调研 Markdown 编辑器、Markdown 渲染方案想了解 AI 大模型如何参与内容生产的人。读完本文你可以掌握 Marp 的核心写法学会用 AI 批量生成幻灯片初稿并完成 PDF、PPTX、HTML 多种格式的导出和发布。1. 用 Markdown 做幻灯片的原理与价值1.1 Markdown 幻灯片本质是“内容与样式分离”传统 PPT 的本质是“画布 对象”。每一页的内容、位置、大小、动画都保存在同一个文件里。这种模型的好处是所见即所得坏处是内容调整和样式调整耦合在一起后续维护成本很高。Markdown 幻灯片换了一种思路内容用纯文本描述渲染时再套用统一样式。你只需要写标题、正文、列表、代码、图片引用剩下的排版交给渲染引擎完成。这样内容文件小、容易做版本管理、也方便被程序批量处理。以 Marp 为例一份最简幻灯片长这样--- marp: true --- # 第一页标题 - 要点一 - 要点二不需要拖拽画布不需要设置字号渲染引擎会自动按主题排版。1.2 AI 在幻灯片工作流中做什么AI 大模型的强项是文本生成与结构化改写正好对应幻灯片制作中最耗时的部分生成大纲给定主题先生成章节结构展开单页内容把大纲扩写成每页要点改写润色把复杂段落压缩成适合演示的短句生成演讲备注为每页生成口语化的讲稿统一语气风格让不同来源的材料合并后风格一致。AI 负责“写什么”Markdown 负责“怎么排版”。两者结合后制作一套 20 页左右的技术分享幻灯片时间可以从几小时压缩到几十分钟。1.3 常见 Markdown 幻灯片工具目前常用的方案主要有三类工具特点适合场景Marp语法简单直接从 Markdown 生成幻灯片支持 VS Code 插件快速入门、技术分享、日常汇报Slidev基于 Vue支持主题、代码高亮、图标、动画扩展能力强对视觉效果要求较高的技术人员Reveal.js老牌 HTML 演示框架Markdown 是其一种内容格式深度定制网页演示本文主角是 Marp因为学习成本最低与 AI 结合最直接也是目前“Markdown 幻灯片”搜索关注度最高的方案之一。2. 环境准备与工具安装2.1 环境要求Marp 本身不依赖特定操作系统Windows、macOS、Linux 都能用。我们在本文中的示例基于常见环境操作版本相关细节请以你实际安装时的 release 信息为准。准备工具清单Node.js 18 或以上版本Marp CLI 依赖 Node 环境一个现代浏览器用于预览 HTML 导出结果文本编辑器推荐 VS Code配合 Markdown 插件使用体验更好Python 3.9用于后续 AI 调用示例脚本。如果你不熟悉 Node.js 安装可以访问 Node.js 官方网站下载 LTS 版本。2.2 安装 Marp CLIMarp 官方提供了命令行工具marp-team/marp-cli推荐全局安装npm install -g marp-team/marp-cli安装完成后验证版本marp --version如果终端能输出版本号说明安装成功。这里要提醒一点Marp CLI 更新比较频繁不同版本的参数有小幅差异执行marp --help可以查看当前帮助信息。2.3 安装 VS Code 插件可选如果你习惯在 VS Code 中编辑 Markdown可以安装官方插件插件名称Marp for VS Code安装方式在 VS Code 扩展面板搜索Marp找到marp-team.marp-vscode安装即可安装后打开.md文件如果文件头部 YAML 配置中有marp: true编辑器右上角会出现预览按钮点击即可实时查看幻灯片效果。2.4 准备 AI 调用环境后面实战会用一个 Python 脚本调用大模型 API。为了不绑定具体厂商示例代码使用 OpenAI 兼容接口风格你需要准备一个可用的 API Key服务商提供的接口地址 base_url你选择的模型名称。按照最小权限原则建议把 API Key 放在环境变量中不要写进代码文件也不要提交到 Git 仓库。# Linux / macOS export LLM_API_KEY你的API密钥 export LLM_BASE_URLhttps://api.example.com/v1 # Windows PowerShell $env:LLM_API_KEY你的API密钥 $env:LLM_BASE_URLhttps://api.example.com/v1这里LLM_BASE_URL只是示例占位请替换成你实际使用服务商提供的地址。3. Marp 核心语法详解Mar 的本质是 Markdown 超集。它在标准 Markdown 的基础上增加了---分页符和 YAML frontmatter 配置。下面按难度拆开讲解。3.1 YAML frontmatter控制全局设置Markdown 文件开头可以写一段由---包裹的 YAML 配置Marp 会读取这段配置作为全局设置。--- marp: true theme: gaia paginate: true size: 16:9 ---常用配置说明marp: true启用 Marp 渲染没有该配置时文件会被当成普通 Markdowntheme幻灯片主题内置default、gaia、uncover三种paginate是否在每页底部显示页码size幻灯片尺寸常见有16:9和4:3class自定义 CSS 类用于配合自定义主题文件backgroundImage全局背景图header/footer全局页眉页脚文字。3.2---分页符在 Marp 中三个连字符---独占一行表示一张幻灯片结束、下一张开始。--- marp: true --- # 第 1 页 这是第一页内容。 --- # 第 2 页 这是第二页内容。注意开头的 YAML frontmatter 也是用---包裹的但位于文件最顶部Marp 会把它解析为配置而不是一个分页符。3.3 内容排版常用写法在幻灯片内你可以使用大部分标准 Markdown 语法标题#到######列表-无序列表、1.有序列表引用;代码反引号包裹的单行代码或三反引号包裹的代码块表格管道符绘制的 Markdown 表格图片。除此之外Marp 还提供了一些页面内指令。1. 背景图片![bg]会让图片铺满整张幻灯片作为背景。也可以指定位置此时背景图位于左侧右侧留出空间放文字内容。2. 多列布局Marp 内置了一些 CSS 类可以实现两栏布局div classcolumns div 左侧内容Markdown 也支持。 /div div 右侧内容。 /div /div3. 数学公式使用$或$$包裹 LaTeX 公式行内公式 $Emc^2$。 独占一行 $$ \sum_{i1}^{n} i \frac{n(n1)}{2} $$4. 高级代码主题Marp 代码块高亮基于 Highlight.js支持常见的语言标注python def hello(): print(Hello Marp)### 3.4 自定义主题 如果内置主题不满足视觉要求可以在 themes 目录中放一个 CSS 文件然后在 frontmatter 中声明主题路径。例如目录结构如下slides/ ├── themes/ │ └── my-theme.css └── deck.mddeck.md 头部配置 yaml --- marp: true theme: my-theme ---Marp 会优先从当前目录的themes文件夹查找同名 CSS 文件。自定义 CSS 的例子/* themes/my-theme.css */ section { background: #f8f9fa; color: #2d3436; font-family: Noto Sans SC, Microsoft YaHei, sans-serif; } section h1 { font-size: 48px; color: #0984e3; border-bottom: 3px solid #0984e3; padding-bottom: 12px; }小结一下Marp 的语法并没有改变 Markdown 的表达能力而是在“分页”和“全局样式”上做了增强。你学习时不需要死记硬背把 frontmatter 配置、---分页、背景图、主题 CSS 这四块理解清楚就能覆盖绝大多数场景。4. 完整实战用 AI 生成一套 Markdown 幻灯片下面我们做一个完整项目AI 根据主题生成 Marp 格式的 Markdown 幻灯片然后用 Marp CLI 导出多种格式。4.1 项目整体结构先规划一个清晰的目录结构便于管理和版本控制。markdown-ai-slides/ ├── scripts/ │ └── generate_slides.py ├── slides/ │ └── tech-share.md ├── output/ │ ├── tech-share.html │ ├── tech-share.pdf │ └── tech-share.pptx └── requirements.txtscripts存放 AI 调用脚本slides存放生成的 Markdown 源文件output存放导出文件requirements.txtPython 依赖。4.2 Python 依赖准备使用 Python 调用大模型接口最低要求是安装openaiSDK。如果使用其他兼容接口依赖包名称可能不同请以服务商文档为准。pip install openairequirements.txtopenai1.0.04.3 编写 AI 生成脚本创建一个scripts/generate_slides.py文件思路如下从环境变量读取 API Key 和 base_url构造 Prompt要求模型按 Marp 语法输出幻灯片 Markdown把模型返回内容写入slides/tech-share.md打印文件路径和字符数方便确认结果。示例代码# 文件路径scripts/generate_slides.py import os from pathlib import Path from openai import OpenAI # 从环境变量读取配置避免把密钥写进代码 api_key os.environ.get(LLM_API_KEY) base_url os.environ.get(LLM_BASE_URL) if not api_key or not base_url: raise ValueError(请先设置 LLM_API_KEY 和 LLM_BASE_URL 环境变量) client OpenAI(api_keyapi_key, base_urlbase_url) PROMPT 请帮我生成一份关于“用 Markdown 与 AI 制作幻灯片”的演示文稿。 要求 1. 使用 Marp 语法文件头部必须包含 YAML frontmattermarp: true, theme: gaia, paginate: true。 2. 页与页之间使用单独的 --- 分隔。 3. 总页数 10 到 15 页。 4. 每页内容控制在 5 个要点以内表达简洁。 5. 至少包含一页代码示例、一页表格。 6. 只输出 Marp Markdown 源码不要输出解释性文字。 if __name__ __main__: response client.chat.completions.create( model你的模型名称, # 请替换为实际模型 messages[ {role: system, content: 你是一个擅长结构化表达的技术文档作者。}, {role: user, content: PROMPT}, ], temperature0.7, ) content response.choices[0].message.content output_dir Path(__file__).resolve().parent.parent / slides output_dir.mkdir(exist_okTrue) output_path output_dir / tech-share.md output_path.write_text(content.strip(), encodingutf-8) print(f已生成: {output_path}) print(f字符数: {len(content)})这段代码里的model、base_url必须和你实际使用的大模型服务保持一致。如果你使用的是本地模型兼容 OpenAI 接口同样可以用这套写法。安全提醒不要在脚本里硬编码 API Key脚本本身也不要提交包含敏感信息的版本到公开仓库。4.4 运行生成脚本确认环境变量设置完成后执行cd markdown-ai-slides python scripts/generate_slides.py预期输出已生成: .../markdown-ai-slides/slides/tech-share.md 字符数: 2368生成的内容是纯文本 Markdown可能格式会因模型输出略有差异。打开文件检查一下 frontmatter 和分页符是否完整。4.5 使用 Marp 预览与编辑用 VS Code 打开slides/tech-share.md如果安装了 Marp 插件点击右上角预览按钮即可看到 HTML 渲染效果。也可以使用 CLI 启动本地预览marp -w slides/tech-share.md-w表示 watch 模式文件每次保存都会自动重新渲染浏览器打开 http://localhost:8080 即可实时预览。4.6 导出 HTML、PDF、PPTXMarp CLI 支持把 Markdown 转成多种格式。导出 HTMLmarp slides/tech-share.md -o output/tech-share.htmlHTML 文件是自包含的可以直接发给别人打开也可以部署到静态服务器。导出 PDFmarp slides/tech-share.md --pdf -o output/tech-share.pdf实际上Marp 导出 PDF 的原理是启动一个无头 Chromium 浏览器渲染页面所以如果你本机缺少相关依赖首次运行可能会提示安装。这时候按提示安装缺失组件即可。导出 PPTXmarp slides/tech-share.md --pptx -o output/tech-share.pptx需要特别说明的是PPTX 导出采用“将每页渲染成图片再放入 PPT”的方式。这样能最大程度保留视觉样式但导出的 PPT 文件不是可编辑的原生形状对象。如果需要拿给不熟悉 Marp 的同事二次编辑这个限制要提前沟通好。如果你的演示文稿有自定义背景图或复杂 CSS 特效导出 PDF 通常比 PPTX 更稳定。4.7 验证输出结构生成完成后slides/tech-share.md应该具备类似结构。为了演示下面给出一段手工编写的 Marp 源码片段你可以对照检查生成的 Markdown 是否符合预期--- marp: true theme: gaia paginate: true --- # 用 Markdown 与 AI 制作幻灯片 分享人你的名字 日期2025 年某月 --- ## 为什么选择 Markdown - 纯文本易维护 - 支持 Git 版本管理 - 内容与样式分离 - 方便 AI 批量生成如果 AI 生成的格式有偏差优先检查三点文件开头是否有marp: true分页符是否是独立的一行---标题层级是否连续不要从#直接跳到####。5. 常见问题与排查思路5.1 生成的 Markdown 无法正确分页现象所有内容挤在一页幻灯片里。原因文件里的分页符不是单独的---或者---前面没有空行被 Markdown 解析成了 setext 标题或普通横线。解决思路打开文件确认分页符单独占一行前后各有一个空行检查是否误用***或___Marp 分页只识别---如果 AI 输出内容中没有分页符可以在 Prompt 中明确强调“页与页之间使用独立的 --- 分隔”。5.2 AI 生成的 YAML 头部缺失现象文件看起来是 Markdown但 Marp 预览不生效主题、页码都没有。原因模型可能漏掉了 frontmatter或者 frontmatter 的键值对写错了缩进。解决思路手写一个最小 frontmatter 塞到文件开头--- marp: true theme: default paginate: true ---如果 AI 输出经常漏配建议 Prompt 中直接给一个模板片段让它基于模板填充而不是从零生成。5.3 本地图片无法显示现象代码中的图片地址为相对路径时预览页面显示裂图。原因Marp 渲染时的工作目录与图片相对路径不一致或图片文件名包含中文/空格导致 URL 解析问题。解决思路尽量使用英文文件名使用相对slides目录的路径例如如果图片不多可以转成 Base64 后嵌进 Markdown保证文件可独立分发网络图片地址要确认可访问不要依赖公司内网图床做对外分享。5.4 导出 PDF 时字体异常、中文变成方块现象PDF 里中文显示为方框或乱码。原因系统缺少中文字体或 Marp 渲染时未能正确指定字体。解决思路在自定义主题 CSS 中指定常见中文字体例如Noto Sans SC、Microsoft YaHei、PingFang SC导出 PDF 前先安装系统级中文字体包先确认 HTML 预览正常再导出 PDFHTML 正常说明字体问题大概率出在系统层。5.5 生成的 PPTX 文字不可编辑现象用 PowerPoint 打开导出文件发现选中文字只能当图片整块移动无法改字号。原因Marp 的 PPTX 导出是基于每页截图实现的不是可编辑矢量对象。解决思路如果需要原生可编辑 PPTMarp 不适合建议换用 Slidev 或其他支持原生 PPT 导出的工具如果只是给他人只读查阅PDF 文件更方便打印和分发。问题现象常见原因解决思路所有内容在一页分页符格式错误检查---是否独立一行主题配置不生效YAML frontmatter 缺失在文件头部补充配置本地图片裂图路径或文件名问题使用英文文件名和相对路径PDF 中文乱码中文字体缺失安装字体并指定字体栈PPTX 不可编辑按图片导出必要时使用 PDF 或原生工具6. AI 与 Markdown 幻灯片结合的进阶用法6.1 设计稳定的 Prompt 模板AI 生成幻灯片质量的下限取决于 Prompt 质量。推荐把 Prompt 结构化拆分角色你是一个擅长结构化表达的技术文档作者。 任务生成 Marp 格式的演示文稿 Markdown。 主题xxx 页数10-15 页 面向人群后端开发工程师 每页结构标题 3-5 个要点 风格简洁、技术化 格式要求YAML frontmatter 使用 marp: true页之间用 --- 分隔不要输出解释性文字。Prompt 越具体Markdown 越规范。建议把这段模板保存在prompts/slide_prompt.md方便后续复用和迭代。6.2 分步生成先大纲后细节一次性让模型生成 20 页完整内容容易出现逻辑重复或内容空洞。更稳妥的做法是两阶段生成。阶段一让模型生成大纲。请为主题“xxx”生成一份 15 页技术分享的目录结构每页给出标题和一句话说明用 Markdown 列表输出。阶段二让模型逐页展开内容。针对下面这一页标题编写内容 标题xxx 要求4 个要点每个要点不超过 20 字使用 Marp 列表语法。分步生成降低了每次请求的复杂度也让 AI 输出更稳定。生成的片段再拼接成完整文件即可。6.3 用 AI 做演讲备注幻灯片内容要简洁但演讲者需要口语化讲稿。可以让 AI 为每页生成备注Marp 导出 PPTX 时备注不会直接体现在画布上但对演讲准备很有帮助。示例 Prompt请为以下幻灯片内容生成演讲备注要求自然口语化时长约 1 分钟不要使用书面语。 内容 ### 为什么选择 Markdown - 纯文本易维护 - 支持 Git 版本管理6.4 批量制作多套幻灯片如果企业内经常需要生成固定模板的分享材料可以写一个批处理脚本把主题列表作为参数循环调用 AI再把生成结果汇总成多个文件。topics [ 微服务拆分的十个问题, MySQL 索引优化实践, 前端工程化落地经验, ] for topic in topics: slide generate_slide(topic) save_to_file(topic, slide)这个思路也适合产品说明书、培训材料、技术周报等场景一套脚本覆盖多类内容。7. 最佳实践与工程建议把“Markdown AI”这套流程用到生产环境时有几个容易被忽略但实际影响很大的点。7.1 把幻灯片当成代码来管理Markdown 是纯文本天然适合放进 Git。建议按照“一个分享主题一个目录”来组织目录内包含slides.md幻灯片源码images/图片素材themes/主题 CSSprompts/AI 提示词模板scripts/生成脚本。这样团队协作时改幻灯片可以走代码评审流程能追溯每一轮改动是谁提交的。长期维护多套幻灯片时这种管理方式的价值会非常明显。7.2 注意内容安全与数据隐私使用 AI 生成幻灯片时一定要控制输入内容边界。公司内部的业务数据、用户隐私、未公开的架构设计不要直接塞进 Prompt 发送给外部模型服务。建议遵循最小权限原则涉及敏感数据的内容不要走外部 AI 服务如确实需要使用支持私有部署的模型服务API Key 通过环境变量注入不要硬编码定期轮换密钥避免密钥泄露后影响范围扩大。7.3 控制单页信息量幻灯片每一页表达一个核心观点最多 5 个要点。AI 生成内容容易写得“满”人工审稿时建议做减法一句标题能说完就不要拆成三段代码只保留关键部分不要整页铺代码图表优先于大段文字演讲备注承载细节幻灯片只留主结构。这样既符合技术分享的观察体验也降低后续排版调整的工作量。7.4 自定义主题模板团队内可以沉淀一套标准主题 CSS把字号、配色、页脚、Logo 统一起来。以后任何人做分享只需要复制主题文件内容简单写视觉依然统一。例如themes/company-style.css中定义主色调、标题字重、页脚展示/* themes/company-style.css */ section::after { content: attr(data-marpit-pagination) / attr(data-marpit-pagination-total); position: absolute; bottom: 16px; right: 24px; font-size: 12px; color: #888; }运行时在 frontmatter 中声明--- marp: true theme: company-style ---7.5 先确认输出格式再做自动化部分团队希望把自动生成的 Markdown 直接转成 PPTX 再交付给业务方。建议先给业务方演示 PDF 和 PPTX 两种版本确认对“可编辑性”要求后再决定导出策略。否则做了大量自动化最后发现对方需要原生可编辑 PPT返工成本很高。8. 结语用 Markdown 做幻灯片核心是解决传统 PPT“内容与样式耦合”的问题引入 AI 之后又把“从空白页开始写文案”这个瓶颈大幅降了下来。建议你先从一次小范围的技术分享开始把 Marp 的语法跑顺再逐步加入 Prompt 模板、自定义主题和批量生成脚本。如果本文对你有帮助可以收藏备用。下一篇可以继续聊聊如何把这份 Markdown 幻灯片接入团队知识库或者用自定义主题统一多场分享的视觉风格。