Marp CLI：用Markdown高效制作技术演示文稿

1. Marp CLI 是什么Marp CLI 是一个基于命令行的 Markdown 幻灯片转换工具它能够将简单的 Markdown 文件转换为各种格式的演示文稿。作为开发者我经常需要在技术分享、产品演示等场合使用幻灯片而 Marp CLI 完美解决了传统幻灯片工具如 PowerPoint 或 Keynote在版本控制、内容复用和编写效率上的痛点。Marp CLI 的核心价值在于纯文本工作流所有内容都用 Markdown 编写可以完美融入 Git 版本控制高效转换一键将 .md 文件转换为 HTML、PDF、PPTX 甚至图片主题定制支持 CSS 自定义幻灯片样式跨平台基于 Node.js 开发Windows/macOS/Linux 全平台支持2. 快速安装指南2.1 前置条件在安装 Marp CLI 前请确保系统已安装Node.js v18 或更高版本推荐使用 LTS 版本任意现代浏览器Chrome/Edge/Firefox用于 PDF/PPTX 转换提示如果只是临时使用可以直接通过 npx 运行无需安装详见后文2.2 安装方式对比安装方式适用场景命令示例npx 临时使用一次性转换无需安装npx marp-team/marp-clilatest slide.md项目本地安装团队协作版本控制npm install --save-dev marp-team/marp-cli全局安装频繁使用多项目npm install -g marp-team/marp-cliHomebrewmacOS 用户brew install marp-cliDocker隔离环境docker pull marpteam/marp-cli我个人推荐项目本地安装方式这样可以确保团队所有成员使用相同的工具版本# 在项目目录下执行 npm init -y npm install --save-dev marp-team/marp-cli安装完成后可以通过以下命令验证是否安装成功npx marp --version # 应输出类似marp-team/marp-cli v4.x.x3. 基础使用教程3.1 创建第一个幻灯片新建一个slide.md文件内容如下--- theme: default --- # 欢迎使用 Marp CLI 这是你的第一张幻灯片 --- ## 第二页 - 列表项 1 - 列表项 2 - 列表项 3Marp 使用---作为幻灯片分页符支持标准的 Markdown 语法以及扩展功能。3.2 常用转换命令3.2.1 转换为 HTMLmarp slide.md -o output.html3.2.2 转换为 PDFmarp slide.md --pdf # 或指定输出文件名 marp slide.md -o presentation.pdf3.2.3 转换为 PowerPointmarp slide.md --pptx # 生成可编辑版本实验性功能 marp slide.md --pptx --pptx-editable3.2.4 转换为图片# 仅标题页 marp slide.md -o title.png # 所有页面 marp slide.md --images png3.3 实时预览模式开发时最实用的功能是 watch 模式文件保存后自动重新生成marp -w slide.md结合浏览器自动刷新扩展如 Live Server可以实现真正的所见即所得开发体验。4. 高级功能详解4.1 主题系统Marp 支持两种方式定义主题使用内置主题--- theme: gaia ---自定义主题 创建custom.css/* theme custom */ section { background: #f3f4f6; color: #333; font-size: 24px; }使用时指定主题文件路径marp slide.md --theme custom.css4.2 演讲者备注在 Markdown 中添加备注不会被显示在幻灯片上--- theme: default --- # 主标题 !-- 这是备注内容只在演讲者视图中可见 --导出备注文本marp slide.md --notes -o notes.txt4.3 全局元数据通过 front-matter 定义幻灯片元信息--- title: 技术分享会 author: 张三 description: 关于Marp CLI的详细介绍 keywords: marp,markdown,slides url: https://example.com image: https://example.com/og-image.jpg ---这些信息会被注入到输出的 HTML/PDF/PPTX 文件中。5. 实战技巧与避坑指南5.1 常见问题解决问题1PDF 转换时提示缺少浏览器解决方案确保已安装 Chrome/Edge/Firefox或明确指定浏览器路径marp --browser-path /Applications/Google Chrome.app/Contents/MacOS/Google Chrome slide.md --pdf问题2本地图片无法在 PDF 中显示解决方案添加--allow-local-files参数注意安全风险marp --pdf --allow-local-files slide.md问题3中文内容显示异常解决方案在主题 CSS 中指定中文字体section { font-family: PingFang SC, Microsoft YaHei, sans-serif; }5.2 性能优化技巧并行处理当转换多个文件时使用-P参数提高速度marp -P 8 slides/*.md缓存利用对于大型项目可以创建 Docker 镜像预装所有依赖增量构建结合--watch模式只重新编译修改过的文件5.3 企业级应用建议CI/CD 集成在构建流程中自动生成演示文稿# GitHub Actions 示例 - name: Build slides run: | npm install npx marp slides/ --pdf -o dist/模板化管理创建企业品牌主题模板统一视觉风格文档化流程将常用命令写入 Makefile 或 package.json scripts{ scripts: { build:slides: marp slides/ --pdf -o dist/, watch:slides: marp -w slides/ } }6. 配置与自定义6.1 配置文件创建marp.config.js进行全局配置module.exports { inputDir: ./slides, output: ./dist, pdf: true, themeSet: [./themes], engine: ({ marp }) marp.use(require(markdown-it-emoji)) }6.2 扩展 Markdown 语法通过自定义引擎添加插件// custom-engine.js import markdownItAttrs from markdown-it-attrs export default ({ marp }) marp.use(markdownItAttrs)使用自定义引擎marp --engine ./custom-engine.js slide.md6.3 高级主题功能利用 CSS 变量实现动态主题/* theme advanced */ :root { --primary-color: #4285f4; --secondary-color: #34a853; } section.primary { background: var(--primary-color); color: white; }在 Markdown 中指定类名!-- 使用 primary 样式 -- !-- _class: primary --7. 与其他工具的对比特性Marp CLIReveal.jsDecksetPowerPoint编写方式MarkdownMarkdownMarkdownGUI版本控制友好✓✓✓✗输出格式多格式HTMLPDF/PPTXPPTX主题定制CSSCSS内置内置实时预览✓✓✓✓学习曲线低中低高价格免费免费付费付费从我的使用经验来看Marp CLI 特别适合技术文档工程师需要将文档自动转换为演示文稿开发者喜欢命令行工作流和版本控制团队协作需要统一的幻灯片制作规范8. 实际案例分享8.1 技术大会演讲我曾用 Marp CLI 准备过一场 50 页的技术分享使用 Git 管理版本历史通过 CI 自动生成 PDF 和 PPTX 版本自定义主题匹配大会视觉规范使用备注功能准备演讲内容整个准备过程比传统工具节省了约 40% 的时间。8.2 产品需求文档将产品 PRD 的 Markdown 文档转换为内部评审用的 HTML 版本带导航给高管的 PDF 精简版跨部门分享的 PPTX 版本一套源码满足多种输出需求维护成本大幅降低。9. 学习资源推荐官方文档 Marp 官网主题画廊 Marp Themes示例仓库 Awesome MarpVS Code 插件Marp for VS Code对于初学者我建议从官方示例开始逐步尝试基础 Markdown 幻灯片添加简单样式尝试转换为不同格式探索高级功能如备注、分栏等10. 个人使用心得经过多个项目的实践我总结了以下最佳实践目录结构标准化/presentation /slides # 源文件 /themes # 自定义主题 /dist # 输出文件 marp.config.js # 配置文件版本控制策略忽略输出文件在 .gitignore 中添加/dist使用 Git 标签管理重要版本性能优化对于大型幻灯片集使用--parallel参数避免在 Markdown 中嵌入大图使用外部引用团队协作创建共享主题模板编写 CONTRIBUTING.md 说明编写规范使用 CI 自动生成最新版本Marp CLI 彻底改变了我制作幻灯片的方式现在所有技术分享都从 Markdown 开始。它的简洁性和灵活性特别适合追求效率的开发者虽然初期需要适应文本编写的方式但一旦掌握就再也不想回到传统的幻灯片工具了。