Marp CLI 完整使用指南：从入门到精通

Marp CLI 是一个强大的命令行工具，能够将 Markdown 文件转换为精美的幻灯片。通过简单的命令，您可以快速创建 HTML、PDF、PowerPoint 文档和图片格式的演示文稿。

项目简介

Marp CLI 是基于 Marp 和 Marpit 框架的转换器命令行接口。它支持多种输出格式，包括静态 HTML/CSS、PDF、PowerPoint 文档和图片。

快速开始

使用 npx 快速体验

如果您只需要一次性转换而不想安装，npx 是最佳选择。只需运行以下命令（需要 Node.js v18 及以上版本）：

# 转换为 HTML
npx @marp-team/marp-cli@latest slide-deck.md
npx @marp-team/marp-cli@latest slide-deck.md -o output.html

# 转换为 PDF
npx @marp-team/marp-cli@latest slide-deck.md --pdf
npx @marp-team/marp-cli@latest slide-deck.md -o output.pdf

# 转换为 PowerPoint 文档 (PPTX)
npx @marp-team/marp-cli@latest slide-deck.md --pptx

# 监视模式
npx @marp-team/marp-cli@latest -w slide-deck.md

# 服务器模式（传递要服务的目录）
npx @marp-team/marp-cli@latest -s ./slides

安装方式

本地安装（推荐）

npm install --save-dev @marp-team/marp-cli

全局安装

npm install -g @marp-team/marp-cli

核心功能详解

转换为 HTML

默认情况下，传递的 Markdown 将转换为 HTML 文件。以下示例将在同一目录下输出转换后的 slide-deck.html：

marp slide-deck.md

使用 --output (-o) 选项可以更改输出路径：

marp slide-deck.md -o output.html

转换为 PDF

传递 --pdf 选项或通过 --output (-o) 选项指定以 .pdf 结尾的输出文件名时，Marp CLI 将尝试通过浏览器将 Markdown 转换为 PDF 文件。

marp --pdf slide-deck.md
marp slide-deck.md -o converted.pdf

PDF 输出选项

• --pdf-notes：当幻灯片页面有 Marpit 演示者备注时，在左下角添加 PDF 备注注释
• --pdf-outlines：添加 PDF 大纲/书签

转换为 PowerPoint 文档

通过传递 --pptx 选项或指定带有 PPTX 扩展名的输出路径，可以进行 PPTX 转换以创建 PowerPoint 文档。

marp --pptx slide-deck.md
marp slide-deck.md -o converted.pptx

生成的 PPTX 包含渲染的 Marp 幻灯片页面和对 Marpit 演示者备注的支持。可以用 PowerPoint、Keynote、Google Slides、LibreOffice Impress 等打开...

转换为 PNG/JPEG 图片

多张图片转换

# 转换为多张 PNG 图片文件
marp --images png slide-deck.md

# 转换为多张 JPEG 图片文件
marp --images jpeg slide-deck.md

输出文件带有页码后缀，如 slide-deck.001.png、slide-deck.002.png 等。

标题幻灯片转换

# 仅将第一页（标题幻灯片）转换为图片
marp --image png slide-deck.md
marp slide-deck.md -o output.png

转换模式

监视模式

当与 --watch (-w) 选项一起传递时，Marp CLI 将观察 Markdown 和使用主题 CSS 的变化。每当文件内容更新时，转换将被触发。

服务器模式

服务器模式通过 HTTP 请求支持按需转换。需要传递 --server (-s) 选项和要服务的目录。

在此模式下，转换后的文件作为访问服务器的结果输出，而不是输出到磁盘。

幻灯片过渡效果

Marp CLI 的 bespoke HTML 模板支持幻灯片过渡动画，当设置 transition 本地指令时，将在幻灯片页面更改时触发。

内置过渡效果

Marp CLI 提供了 33 种内置过渡效果：

自定义过渡效果

您还可以在主题 CSS 和 Markdown 内联样式中定义自定义过渡和动画。我们通过您的创造力提供无限的可扩展性。

简单关键帧声明

/* 定义 `dissolve` 过渡 */
@keyframes marp-transition-dissolve {
  from {
    opacity: 1;
  }
  to {
    opacity: 0;
  }
}

配置系统

Marp CLI 可以通过文件配置选项，例如 marp.config.js、marp.config.mjs（ES 模块）、marp.config.cjs（CommonJS）、.marprc（JSON / YAML）以及 package.json 的 marp 部分。

package.json 配置示例

{
  "marp": {
    "inputDir": "./slides",
    "output": "./public",
    "themeSet": "./themes"
  }
}

主题系统

覆盖主题

您可以使用 --theme 选项覆盖要使用的主题。例如，使用 Marp Core 中的 Gaia 内置主题：

marp --theme gaia

使用自定义主题

通过传递 CSS 文件的路径，也可以轻松使用用户创建的自定义主题。

marp --theme custom-theme.css

主题集

--theme-set 选项必须指定由多个主题 CSS 文件组成的主题集。

# 多个主题 CSS 文件
marp --theme-set theme-a.css theme-b.css theme-c.css -- deck-a.md deck-b.md

# 主题目录
marp --theme-set ./themes -- deck.md

引擎配置

Marp CLI 调用基于 Marpit 框架的转换器作为"引擎"。通常我们使用捆绑的 Marp Core，但您可以通过 --engine 选项将转换引擎切换到另一个基于 Marpit 的引擎。

使用 Marpit 框架

例如，您可以使用纯 Marpit 框架转换 Markdown：

# 安装 Marpit 框架
npm i @marp-team/marpit

# 指定引擎使用 Marpit
marp --engine @marp-team/marpit marpit-deck.md

请注意 Marpit 没有提供主题。如果要在演示文稿中包含内联样式，或者通过 --theme 选项传递 CSS 文件，效果会更好。

实用技巧

快速启动命令

marp --watch presentation.md

主题切换技巧

使用 --theme 参数即时更换主题。

导出优化设置

根据目标平台调整输出参数。

通过本指南，您已经掌握了 Marp CLI 的核心架构和使用方法。现在就开始使用这个强大的工具，让您的演示文稿制作效率提升到新高度！