Marp CLI快速入门

Marp CLI

定义

Marp CLI 是 Markdown Presentation Ecosystem 的命令行接口工具，能够将 Markdown 文件转换为 HTML、PDF、PowerPoint 和图片格式的演示文稿。

技术定位

Marp CLI 位于 文档工具链 中的演示文稿生成层，基于 Marpit 框架和 @marp-team/marp-core 引擎，为开发者提供纯文本驱动的幻灯片创作体验。

核心特性

Markdown 原生语法 ：使用 CommonMark 标准 Markdown 编写幻灯片，通过 --- 分隔页面
多格式导出：支持输出为 HTML、PDF、PPTX、PNG/JPEG 等格式
主题系统 ：内置 default、gaia、uncover 三套官方主题，支持自定义 CSS 主题
指令控制 ：通过 Directives（如 ）控制主题、分页、样式等
实时预览 ：提供 --watch 模式和本地服务器预览功能
CI/CD 友好：可集成到 [[GitHub Actions]]、[[GitLab CI]] 等自动化流程

工作原理

转换流程

HTML
PDF
PPTX
Image
Markdown 文件
Marp Core 解析器
Marpit 框架
输出格式
静态网页
Chrome Headless
PowerPoint 文档
PNG/JPEG

关键机制

Directives 系统 ：通过 HTML 注释语法（）注入元数据
- 全局指令：影响整个文档（如 theme、paginate）
- 局部指令：仅作用于当前页面（如 _class、_backgroundColor）
主题渲染：基于 [[CSS]] 的主题系统，支持 Scoped CSS 和变量覆盖
PDF 生成：通过 [[Puppeteer]] 驱动 Chrome 无头浏览器进行打印

快速上手

安装

bash 复制代码

# 全局安装
npm install -g @marp-team/marp-cli

# 项目依赖
npm install --save-dev @marp-team/marp-cli

最简示例

创建 slides.md：

markdown 复制代码

---
marp: true
theme: gaia
paginate: true
---

# 欢迎使用 Marp
这是第一页幻灯片

---

## 核心功能
- Markdown 语法
- 多格式导出
- 自定义主题

---

<!-- _class: lead -->
# 谢谢观看

转换命令

bash 复制代码

# 生成 HTML
marp slides.md

# 生成 PDF（需要 Chrome/Chromium）
marp slides.md --pdf

# 生成 PowerPoint
marp slides.md --pptx

# 实时预览
marp -w -s slides.md

预期结果

HTML 输出：slides.html（包含内联 CSS）

PDF 输出：slides.pdf（保留字体和样式）

预览服务器：http://localhost:8080

优缺点对比

维度	优势 (Pros)	局限 (Cons)
易用性	纯文本编辑，版本控制友好	复杂动画需要自定义 CSS
性能	静态输出，加载速度快	PDF 生成依赖 Chrome，资源占用高
扩展性	支持自定义主题和插件	交互功能有限（非 Web 应用）
生态	与 [[VS Code]]、[[Obsidian]] 集成良好	社区主题资源相对较少
跨平台	Node.js 环境即可运行	PPTX 导出功能相对基础

自定义主题

css 复制代码

/* custom-theme.css */
@theme custom
@import 'default';

section {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  color: white;
}

h1 {
  border-bottom: 3px solid #ffd700;
}

使用主题：

bash 复制代码

marp --theme custom-theme.css slides.md

配置文件

创建 .marprc.yml：

yaml 复制代码

inputDir: ./slides
output: ./dist
pdf: true
allowLocalFiles: true
themeSet: ./themes

工具	特点	适用场景
Marp CLI	Markdown 原生，CLI 驱动	技术文档、代码演示
Reveal.js	Web 框架，交互丰富	学术报告、产品发布
Slidev	Vue 驱动，组件化	前端开发者演讲
Beamer	LaTeX 生态，学术风格	数学/物理论文答辩

生态工具

Marpit：底层幻灯片框架

Marp for VS Code：官方 VS Code 扩展

Marp Core：核心转换引擎

Marp React：React 组件封装

Marp CLI快速入门

目录

Marp CLI

技术定位

核心特性

工作原理

转换流程

关键机制

快速上手

安装

最简示例

转换命令

优缺点对比

自定义主题

配置文件

相关技术对比

生态工具

参考资源

Sources