Marp 幻灯片指南：如何用一份 Markdown 文件搞定演示文稿的写作、美化与多格式导出

Marp 幻灯片指南：如何用一份 Markdown 文件搞定演示文稿的写作、美化与多格式导出

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

还在 PPT 软件里拖文本框、调字号、对齐色块吗？Marp走的是另一条路：把整份 Markdown 演示文稿还原成一个.md文件，改内容像写文档一样快，换皮肤像改 CSS 一样直观，最后一条命令就能转成 HTML、PDF 或 PPTX。这篇指南带你从第一页幻灯片写到最终导出，全部基于纯文本，不碰任何图形拖拽。

先说场景：你的幻灯片还藏在 PPT 的格式陷阱里吗

日常做演示文稿，你大概率遇到过这些情况：

• 想改一个标题的颜色，得先找到文本框，再翻三层菜单；
• 同事发来的 PPT 在你机器上排版全乱，字体也没了；
• 演讲稿迭代了三版，diff 全是二进制噪音，没法进 Git 对比。

Marp 的思路是把幻灯片当成一份纯文本：内容就写在 Markdown 里，页面之间用一条分隔线切开。这样带来的直接好处是：

• 改一行字，保存即生效；
• 整套文稿放进仓库，版本历史和协作审查都是现成的；
• 同一份源文件，按需输出网页版、打印版或 Office 版。

你不需要放弃对画面的控制——Marp 的样式层就是标准 CSS，后面会细讲。

Marp 生态怎么分家：Marpit、Marp Core 与 Marp CLI 各管一摊

Marp 不是一坨单体软件，而是分成三个可以单独取用的部分：

• Marpit：负责"Markdown 怎么变成一页页幻灯片"这件事本身——按分隔符切页、解析指令、处理图片语法这类骨架功能都出自它；
• Marp Core：在骨架之上加入成品能力，比如内置主题、公式渲染、GFM 增强语法；
• Marp CLI：转换器外壳，把前两者的能力接到你的命令行，负责产出 HTML、PDF、PPTX 和图片文件。

打个比方，这像一条流水线：Marpit 是传送带，Marp Core 是加工工序，Marp CLI 是打包出货口。因为各层独立，你既可以用 CLI 直接干活，也能在自己的 Node.js 项目里只引 Core 做定制。

选一条上手路线：命令行直转或 VS Code 边写边看

Marp 提供两种使用姿势，按你的习惯挑：

Marp for VS Code适合不想碰终端的人：装好扩展、打开 Markdown 文件就能看效果。Marp CLI适合批量处理、接 CI、管道串联，以及需要挂插件的场景。

命令行：一条 npx 命令出活

只要装了 Node.js（>= 12），不安装任何全局包也能试水：

npx @marp-team/marp-cli@latest markdown.md

想长期用，macOS 上brew install marp-cli、Windows 上scoop install marp都只有一行；也提供独立二进制和 Docker 官方镜像。注意：导出 PDF 或 PPTX 时，本机要有 Chrome、Edge 等 Chromium 内核浏览器参与渲染。

编辑器：装上扩展就能实时预览

在 VS Code 里安装Marp for VS Code扩展，新建一个.md文件，点编辑器工具栏上的 Marp 图标（Toggle Marp feature for current Markdown），它会在文件头部帮你插好声明，然后打开 Markdown 预览就开始写幻灯片。

写第一张幻灯片：声明启用、分隔符切页与内置语法增强

在任意.md文件开头加三行，它就成为 Marp 文稿：

--- marp: true ---

之后的规则很朴素：

• 切页：写一条分隔线---（不想处理空行时，可改用***、___或- - -），每切一次就是一页；
• 兼容：Marp 基于 CommonMark 标准，只往上加东西不删改——你写的文件在任何 Markdown 编辑器里都读得懂；
• 增强：段落里的回车自动换行；表格、emoji 短码、删除线、URL 自动链接、代码高亮等 GitHub 风格语法开箱即用；
• 安全：大部分 HTML 标签默认禁用，只放行<style>和<br/>两个标签，想开更多需要显式配置。

第一页写个一级标题和一行副标题，保存，预览里你已经有一张能看的幻灯片了。

指令（Directives）速查：页码、背景、页眉页脚都靠它

Marp 在 Markdown 之外加了一套叫Directives（指令）的开关，写法就是 YAML，放在文档开头的 front matter 里，或者写在任意一页的 HTML 注释中：

<!-- theme: default paginate: true -->

指令分两种粒度：

• 全局指令：管整份文稿。如theme（主题）、size（页面尺寸）、math（公式引擎）、title/author/description（元信息）等；
• 单页指令：管某一页。如paginate（页码）、header/footer（页眉页脚）、backgroundImage/backgroundColor（背景）、color（文字色）等。

📌 单页指令有个容易忽略的机制：它会向下继承。在第三页设了背景色，第四页没写就会跟着用。想让某个值只作用于当前页，在指令名前加下划线，例如_color: blue——这一页变蓝，下一页自动回到继承的颜色。

几个实用技巧：

• 想让页码从第二页才开始？把paginate: true移到第二页声明即可；
• header/footer的内容里可以写行内 Markdown（加粗、图片都行），YAML 里记得用引号包起来；
• 中途想撤掉页眉页脚，把值写成空字符串就能重置。

主题系统与 CSS：换肤、注入样式、公式排版

Marp 坚持内容与样式分离：你只管写内容，长什么样交给 主题 决定。

• 换主题：front matter 里写theme: 主题名。官方主题分亮色和暗色两套，深浅切换就改一个词；
• 改样式：只要你写过网页 CSS，就能改幻灯片。style全局指令可以注入一段 CSS 微调主题细节；单页想临时改，直接在该页写一个<style>块；
• 公式：支持 Pandoc 风格数学排版——$...$写行内公式，$$...$$写居中公式块。默认用 MathJax 渲染，也可通过math: katex指令切到 KaTeX；建议在 front matter 里显式声明引擎，避免不同版本渲染结果漂移。

也就是说，"主题"在 Marp 里不是什么黑盒皮肤，就是一套 CSS——你会改样式，就等于会做主题。

把存量文档变成幻灯片：headingDivider 按标题级别自动切页

手上已经有一篇结构完整的 Markdown 长文，不想一页页手工切？heading divider 指令帮你自动分页：

<!-- headingDivider: 2 -->

这行指令告诉 Marp：遇到二级标题就开新页（一级标题同样触发）。某节内容太多溢出一页，就把级别调到 3，让它按三级标题切；想要完全精确的控制，可以传数组，例如headingDivider: [1, 3]，只在一级和三级标题处分页。原有的---分隔符依然有效，两种方式可以混用。

这是把"写文档"和"做演讲"合一的捷径：同一份源稿，日常是文档，需要汇报时加一行指令就是幻灯片。

批量导出幻灯片：Marp CLI 转 HTML / PDF / PPTX 与碎片化列表

写完之后，交给 Marp CLI 统一出货。

几种输出的定位不同：

• HTML：可以发到网上，保留交互内容，比如逐条出现的列表；
• PDF：任何能放 PDF 的环境都能放映，离线场景首选，官方也推荐这是最简单的放映方式；
• PPTX：要进 PowerPoint 手工补内容的场合用；
• 图片：按页产出 PNG/JPEG，适合分享单页截图。

Marp 刻意追求跨格式渲染一致——同一页内容，HTML、PDF、PPTX 里看起来应该是一样的，你不用为某个格式单独修版式。

两个值得知道的细节：

1. 碎片化列表：用*开头的无序列表、1)形式的有序列表，在 HTML 输出里会逐条淡入，控制观众注意力；导出 PDF/PPTX 时它们就显示为完整列表。
2. 接自动化：CLI 可以批处理一整个目录、配合管道和重定向，也支持通过配置文件传高级选项，直接塞进 CI 流水线做服务端转换。

VS Code 写幻灯片：实时预览、诊断与大纲面板

如果选了扩展路线，Marp for VS Code 除了实时预览，还给你三件顺手的事：

• 指令补全：写<!-- the时自动提示theme、title等指令名，不用背拼写；
• 诊断：指令写错、主题名不存在，编辑器里直接标出来；
• 侧边栏大纲：左侧面板列出整份文稿的页面结构，长文稿里跳页、整理顺序比翻文件快得多。

改完即导出：扩展内置导出命令，PPTX 或 PDF 直接落盘，拿去接着在 PowerPoint 里补内容，或者直接开投。

装插件、接 CI：把 Marp 嵌进自己的管线

到这里你已经跑通了"写 → 美化 → 导出"的主线。剩下的是把 Marp 变成你自己的基础设施：

• 挂插件：Marp CLI 基于 Marpit 的可插拔架构，可以接 markdown-it 插件加新语法、自定义指令、塞入自己的主题集；
• 团队流水线：把导出命令接进 CI，文档合并后自动产出最新 PDF 放进发布物，评审和归档都不用人工跑一遍；
• 参与上游：这个仓库（Marp 生态的入口仓库，采用 Yarn workspaces 组织，官方站点用 Next.js 13 + TypeScript + Tailwind CSS 构建）以 MIT 协议开源，文档 里的每一篇都欢迎补全和纠错。

下一步可以做的具体三件事：给自己挑一套主题，在style指令里写几行 CSS 把它改成你的团队配色；给一个真实项目把导出接进 CI；最后把这次做的幻灯片仓库化，让下次的 diff 只留下你真正改的内容。

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