Marp 入门指南：用 Markdown 打造 Markdown Presentation Ecosystem 幻灯片

• 前端
• 文档

Marp（MarkdownPresentation Ecosystem）是一套以纯 Markdown 编写演示文稿的开源生态。本文以仓库中的官方介绍文档 website/docs/introduction/whats-marp.md 为主体，结合本仓库（README.md、package.json、website/docs/manifest.yaml）的源码与文档结构，系统讲解 Marp 的设计理念、核心概念、可插拔架构，以及 CLI 与 VS Code 两种工具的安装与选用方式。读完本文，你将掌握 Marp 幻灯片的基本写法、主题与指令的运作机制，并能够在自己的机器上完成从安装到导出 PDF/PPTX/HTML 的完整流程。

Marp 是什么

Marp 是 "Markdown Presentation Ecosystem"（Markdown 演示文稿生态）的缩写，它的目标非常明确：为“用 Markdown 写演示文稿”这件事提供一流的体验。

在传统工作流中，做 PPT 往往意味着在 PowerPoint 或 Keynote 里手工排版、拖拽元素，注意力被分散到“如何生成这张幻灯片”的代码与操作上。Marp 则把重心拉回到内容本身：作者只需专注于演示文稿的逻辑结构，用最朴素的 Markdown 把要点写出来，剩下的事情交给生态内的工具链。

需要特别强调的是，本仓库是一个生态入口仓库（entrance repository）。正如 package.json 中描述的那样，它的定位是 "The entrance repository of Markdown presentation ecosystem"，仓库主体内容位于website目录（Next.js 站点），而真正的引擎、核心与工具由若干子项目构成。理解这一点，有助于你在阅读后续“可插拔架构”与“生态全家桶”两节时建立全局视角。

一段真实的 Marp 幻灯片：先看效果

官方介绍文档给出的第一个示例就是一段完整的、可直接运行的 Marp 幻灯片源码。它展示了 Marp 的三个基础要素：YAML front matter（启用 Marp 并指定主题）、Markdown 内容、以及用---分割的多页结构：

--- marp: true theme: uncover --- [![Marp w:240](https://raw.gitcode.com/gh_mirrors/mar/marp/raw/b4fcffdd7f764441e5c9e2581d6ef2f8c860d304/website/public/assets/marp-logo.svg?utm_source=gitcode_repo_files)](https://link.gitcode.com/i/3cf3c0ee1c2067efdad7d18ba4379d8f) # **Marp** Markdown Presentation Ecosystem --- <!-- paginate: true --> ## What's Marp? Marp provides a great experience for _writing_ presentations with Markdown. :pencil: ```markdown # Slide 1 foo --- # Slide 2 bar ```

这段代码展示了几个关键点：

• marp: true：在 front matter 中显式启用 Marp 功能（VS Code 扩展也靠这个开关识别 Marp 文档）；
• theme: uncover：选用内置的uncover主题，Marp 内置了多套可直接使用的主题（详见theme指令）；
• <!-- paginate: true -->：以 HTML 注释形式定义局部指令，为后续幻灯片开启页码；
• ---水平分隔线：Marp 依据水平分隔线把一份 Markdown 文档切分成多张幻灯片。

文档中这类带有marp标记的代码块是可以直接渲染成真实幻灯片的，你可以把它粘贴到 VS Code 的 Markdown 预览中立即看到效果。

四大核心设计理念

基于 CommonMark：兼容一切 Markdown 生态

Marp 的 Markdown 语法建立在CommonMark规范之上。CommonMark 是 Markdown 的统一规范，社区中大多数编辑器、渲染器都遵循它。Marp 选择 CommonMark 的原因有两个：

1. 最大兼容性：你的 Marp 文档在任何支持 CommonMark 的编辑器或渲染器中都不会“走样”；
2. 超集而非另起炉灶：Marp 只在 CommonMark 之上增加少量扩展语法，这意味着你已有的 Markdown 写作习惯可以无缝迁移。

用文档中的话说：Marp only adds a few additional features on top of CommonMark, so your Marp document will look good regardless of what software you used to edit or render Markdown——即便你换了编辑/渲染工具，文档效果依然一致。

在 website/docs/guide/how-to-write-slides.md 中可以看到这些“额外特性”的具体清单：段落内换行自动转为<br />、支持 GFM 的自动链接/Emoji/删除线/代码高亮/表格、以及<style>与<br />两个默认放行的 HTML 标签等。出于安全考虑，其他 HTML 标签默认禁用，需要按所用工具显式开启。

主题 CSS：内容与样式彻底分离

会一点 HTML 和 CSS，就能轻松定制 Marp 幻灯片的观感。Marp 的主题系统允许你用纯 CSS定义幻灯片样式，其背后是经典的"Separation of content and style"（内容与样式分离）设计原则：

• 作者专注内容（Markdown）；
• 社区贡献的主题（纯 CSS）负责样式；
• 两者通过theme指令解耦，同一份内容可以随时套用不同主题。

这种设计让“使用社区做好的设计”变得极其简单——不需要改任何内容，只需切换theme名称即可。你可以通过style指令为整套幻灯片补充 CSS 微调，也可以借助_class等指令做局部覆盖。

导出 PDF / PPTX / HTML：跨格式渲染一致是硬目标

Marp 对格式转换提供一等公民（first-class）支持，并且把“跨格式渲染一致”当作首要目标：同一份幻灯片导出的 PDF、PPTX、HTML 三个版本应当看起来完全一样，用户不需要担心换一种格式就会破坏排版。

文档同时给出了一条重要的定位说明：Marp 并不是一款独立的演示软件。推荐的演示方式是：

上手简单：CLI 与 GUI 双通道

生态同时提供命令行（Marp CLI）与图形界面（VS Code 扩展）两条创作通道。创建一套幻灯片的最小成本是：安装 Marp，然后写一个 Marp 格式的 Markdown 文件。唯一的前提是：如需导出 PDF/PPTX，本地需装有 Chrome、Edge 或其他 Chromium 内核浏览器（转换引擎依赖 Chromium 渲染）。

• Marp CLI：一条命令把 Markdown 转为 HTML/PDF/PPTX；
• VS Code 扩展：实时预览幻灯片、提供 Marp 语法特性（补全、诊断、悬停提示）与导出命令。

可插拔架构：基于 Marpit 框架

Marp 的底层是Marpit framework——“一个用 Markdown 生成幻灯片套件的精简框架”（the skinny framework for creating a slide deck from Markdown）。Marpit 采用可插拔架构，开发者可以通过插件为其增加能力。这一架构最终通过 Marp CLI 向终端用户开放了定制入口，官方文档列出的可扩展点包括：

• 新增 Markdown 语法：兼容 markdown-it 插件体系；
• 自定义指令（directives）：扩展 Marp 的 YAML 指令系统；
• 提供自定义主题集：交付自己的主题 CSS 集合。

“Push the limits of Marp as you like!”——这句话正是 Marp 生态开放性的注脚：从“改一行 CSS”到“写一个 markdown-it 插件”，定制的深度由你自己决定。

从仓库结构看生态全家桶

本仓库 README.md 用 “Marp family” 一节清晰地罗列了生态中的各个角色，这也是理解“可插拔架构”的完整上下文：

• Marpit：从 Markdown 生成幻灯片套件的底层框架，可插拔架构的根基；
• Marp Core：Marp 转换器的核心，提供实用特性与内置主题（built-in themes）；
• Marp CLI：基于 Marp Core/Marpit 的命令行界面，可转换为 HTML、PDF、PPTX 及图片；
• Marp for VS Code：在 VS Code 中预览 Marp Markdown 幻灯片稿的扩展。

从 website/docs/manifest.yaml 的文档结构可以看出，本站点将文档划分为 Introduction（whats-marp / install）、Guide（how-to-write-slides / directives / theme / heading-divider / image-syntax / fragmented-list / fitting-header / math-typesetting）与 Tools（marp-cli / marp-for-vs-code）三大板块；其中 Tools 板块在本仓库内目前保留为入口页（stub），Marp CLI 与 Marp for VS Code 的完整能力说明分别在其各自的独立子项目中维护。这套“入口仓库 + 多子仓库”的组织方式，正是生态可插拔、可独立演进的工程基础。

开始使用：选 CLI 还是 VS Code？

要开始创作，你必须安装Marp CLI或VS Code 扩展二者之一。website/docs/introduction/install.md 给出了两者的基础对比：

Marp for VS Code：不熟悉命令行的用户可以直接选择它，所有基础 Marp 功能都已涵盖；即便是 CLI 老手，也可能因为 VS Code 的语法补全与实时预览而偏爱用它创作。

Marp CLI更适合以下场景：

• 用自己偏好的编辑器（如 vim）编写 Markdown 与主题 CSS；
• 批量处理（batch processing）；
• 通过管道（piping）与重定向与其他工具组合；
• 持续集成（CI）；
• 服务端转换；
• 设置 Marp 的高级配置；
• 在 Node.js 项目中使用 Marp；
• 使用 Marp / Marpit / markdown-it 插件；
• 使用其他 Marpit 风格（flavored）的引擎。

安装 Marp for VS Code

1. 安装 Visual Studio Code；
2. 安装 Marp for VS Code 扩展；
3. 新建并打开一个扩展名为.md的 Markdown 文件；
4. 在编辑器工具栏的 Marp 图标中选择Toggle Marp feature for current Markdown命令，它会自动在文件 front matter 中加入：

   --- marp: true ---

5. 打开 VS Code Markdown 预览，开始写作。

安装 Marp CLI

Homebrew（macOS）

brew install marp-cli

Scoop（Windows）

scoop install marp

Node.js（npx 一次性转换）

如果已安装 Node.js（文档要求 Node.js >= 12），可以不经安装、直接用npx（即npm exec）做一次性转换：

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

安装到 Node 项目

npm install --save-dev @marp-team/marp-cli npx marp markdown.md

yarn add --dev @marp-team/marp-cli yarn exec markdown.md

也可以将marp命令全局安装，但官方文档明确提示这样做并不推荐。此外还提供独立二进制（从发布页下载）与官方 Docker 容器两种方式。作为参考，本仓库采用 Yarn workspaces 管理（见 package.json 的workspaces: ["website"]），与 Marp 生态各 npm 包的使用习惯一致。

快速掌握 Marp 语法要点

这里补充 website/docs/guide/how-to-write-slides.md 中与“上手”直接相关的语法要点，方便你读完本文就能写出第一套幻灯片。

幻灯片分割：用水平分隔线（如---）切分幻灯片。需要注意，根据 CommonMark 规范，---前后可能需要空行；如果不想加空行，可以用下划线___、星号***或带空格的分隔线- - -代替。

扩展语法：

• 段落内换行自动转为<br />（也可显式书写<br />标签）；
• 某些不常见的列表标记（*、1)）具有特殊含义，用于碎片化列表（详见 website/docs/guide/fragmented-list.md）；
• 启用部分 GFM 特性：URL 自动链接、Emoji 短代码、删除线（~~strike~~）、代码块语法高亮、表格；
• HTML 标签默认大多禁用，仅放行<style>（用于微调主题）与<br />；如需开启全部 HTML 标签，必须在所用的 Marp 工具中显式 opt-in。

指令（Directives）：Marp 用一套 YAML 语法扩展——“指令”来控制主题、页码、页眉页脚等元素。指令可以写在 HTML 注释中，也可以写在文档开头的 YAML front matter 里。指令分为两类：全局指令（作用于整套幻灯片，如theme、size、headingDivider、math、title、author、description、keywords、url、image、style、marp）和局部指令（作用于单页，如paginate、header、footer、class、backgroundColor、backgroundImage、color等）。局部指令会向后续页面继承，加下划线前缀（如_color）可让指令只作用于当前页。详见 website/docs/guide/directives.md。

作者与许可证

Marp 由 Marp team 维护（目前实际由维护者 Yuki Hattori（@yhatt。

小结

从官方介绍文档出发可以看到，Marp 的定位清晰而克制：以 CommonMark 为语法基石，以 CSS 实现内容与样式分离，以“跨格式渲染一致”为转换目标，以 Marpit 的可插拔架构支撑生态扩展，再以 CLI + VS Code 双通道降低上手门槛。它不试图成为独立的演示软件，而是把“写幻灯片”这件事彻底简化为“写 Markdown”。接下来你可以前往 website/docs/guide/how-to-write-slides.md 系统学习幻灯片语法，或参考 website/docs/introduction/install.md 安装工具后立即动手创作第一套幻灯片。

• 前端
• 文档