用 Markdown 写幻灯片有多快？Marp 从入门到团队落地的完整指南

【免费下载链接】marpThe entrance repository of Markdown presentation ecosystem项目地址: https://gitcode.com/gh_mirrors/mar/marp

准备一次技术分享或内部培训时，你是否还卡在 PowerPoint 的拖拽排版上？Marp 让你直接用 Markdown 写幻灯片：一个.md文件就是整份演示文稿，改完一条命令就导出成 PDF。下面这份 Marp 入门教程，从五分钟上手讲到团队工程化落地，帮你把 Markdown 演示文稿变成真正好维护的资产。

五分钟装上 Marp 并导出第一份 PDF

Marp 提供两条入口，任选其一即可开写：Marp CLI（命令行）和Marp for VS Code（编辑器扩展）。新手最省事的是扩展路线——装好 VS Code 后，从扩展市场安装 Marp for VS Code，新建一个.md文件，点右上角的 Marp 图标启用，它会自动写入marp: true，打开预览就能边写边看。

如果偏爱命令行，无需预先安装，借npx跑一次即可：

npx @marp-team/marp-cli@latest deck.md npx @marp-team/marp-cli@latest deck.md --pdf

一条命令生成 HTML，加--pdf得到可投屏的 PDF

下面是最小可用的幻灯片文件，两页、带主题与页码：

--- marp: true theme: gaia paginate: true --- # 我的第一份幻灯片 今天聊聊 Marp 的核心玩法。 --- ## 第二页 - 用 `---` 分隔每一页 - 保存即预览

存为deck.md，再跑一次上面的命令，你就有了第一份 Markdown 幻灯片。更多写法细节可看如何编写幻灯片。

三个核心能力：指令、主题与导出

用指令控制全局与单页

Marp 通过「指令」微调幻灯片，写法有两种：文件顶部的 YAML front matter，或任意页里的 HTML 注释。指令分两类，全局指令影响整份文稿，局部指令只针对当前页（且默认会被后续页继承）。

--- theme: uncover size: 16:9 paginate: true --- <!-- backgroundColor: #fffbe6 --> <!-- _color: #333 -->

theme、size是全局指令；backgroundColor、color是局部指令。给局部指令加下划线前缀（如_color）表示「只影响当前页，不往后继承」。想看完整字段对照，读指令系统说明。

局部指令默认向下继承，加_前缀可锁定在当前页

换主题与写自定义 CSS

内置default、gaia、uncover三个主题，改一行theme即可切换。Marp 坚持内容与样式分离：你只管写 Markdown 正文，视觉交给主题 CSS。想统一品牌色，用style指令或独立主题文件覆写即可，无需改动正文。系统还提供 CSS 变量方便调色，完整做法见主题定制指南。

选对导出格式：HTML、PDF、PPTX

三种输出各有所长：

• PDF：跨平台一致、无网也能投屏，是现场演讲的首选。
• HTML：可部署到内网或公网，支持点击逐条展开的列表等交互。
• PPTX：导出后能塞回 PowerPoint 继续手工补页。

生成 PDF 与 PPTX 依赖本机装有 Chrome、Edge 等 Chromium 系浏览器，CLI 会自动调用它们完成渲染。

两种工作模式：编辑器实时预览 vs 命令行批处理

编辑器模式（Marp for VS Code）：写 Markdown 的同时在右侧看到成型的幻灯片，带语法补全、错误诊断和一键导出。不熟悉命令行、需要即时反馈的人，从这里起步最顺。

左栏写 Markdown，右栏同步渲染幻灯片

命令行模式（Marp CLI）：适合批量转换、管道串联、CI 自动化，以及挂载 Marpit / markdown-it 插件等高级场景。日常写稿可以打开--watch监听文件变化自动重转，配合--preview在预览窗口里实时核对效果。

进阶玩法：过渡动画与团队统一主题

给 HTML 输出加上翻页过渡，演示会立刻更有节奏。用局部指令transition选择内置效果，marp deck.md --preview即可查看：

--- transition: fade --- # 带淡入淡出的页面

内置不够用时，可用@keyframes marp-transition-名称注册自定义动画，再配合view-transition-name做出元素「变形」的连贯动效。做法详见自定义过渡效果。

团队协作时，把公司字体、配色沉淀成一份主题 CSS，约定所有演示统一theme: 你们团队的主题名。内容作者与视觉设计者各管一摊，风格自然一致。

工程化落地：把幻灯片当代码管

• Git 协作：幻灯片本质是.md文本，直接进仓库，走 diff、评审、回滚，多人改动可追溯。
• CI 自动导出：在流水线里加一步marp，每次合并后自动产出最新 PDF/HTML，发布即生效。
• 并入文档站：把演示页与项目文档放在同一站点下，用相对路径引用，一处更新两处同步。

仓库自带的 docs 目录 就是一个「文档站 + 演示内容」共存的参考结构。

常见坑与优化建议

• 图片体积：优先压缩后的横版图，避免动辄几 MB 的原图拖慢首屏。
• 字体加载：自定义字体尽量用系统字体或按需加载，防止布局跳动。
• 对比度：深色主题注意文字与背景的对比度，兼顾可读性与可访问性。
• 分页误判：front matter 的前后两条---会被识别为元数据，真正的分页要从第二条线之后开始。
• 导出失败：PDF/PPTX 报错先确认本机已装 Chromium 系浏览器。

收尾

Marp 把 Markdown 演示文稿变成可版本控制、可自动化的内容生产线，适合写技术分享、内部培训和产品文档的团队。下一步，先按上面的五分钟流程装好工具，用--pdf导出你的第一份幻灯片，再逐步接入团队主题与 CI。

【免费下载链接】marpThe entrance repository of Markdown presentation ecosystem项目地址: https://gitcode.com/gh_mirrors/mar/marp