---
title: "Marp 学习资料汇编"
source:
  - "https://github.com/marp-team/marp"
  - "https://github.com/marp-team/marpit"
  - "https://github.com/marp-team/marp-cli"
  - "https://github.com/JichouP/obsidian-marp-plugin"
  - "https://samuele-cozzi.github.io/obsidian-marp-slides/"
author:
  - "[[Marp Team]]"
  - "[[JichouP]]"
  - "[[Samuele Cozzi]]"
created: 2026-04-07
description: "Marp 生态系统学习资料汇编：Marpit 框架、Marp CLI、Obsidian Marp 插件"
tags:
  - "clippings"
  - "marp"
  - "presentation"
  - "obsidian"
rating: 4
---

## 1. Marp 生态系统概述

Marp 是一个用纯 Markdown 编写演示文稿的生态系统。

核心组件：

| 组件 | 说明 |
|------|------|
| **Marpit** | 瘦框架，将 Markdown 转为幻灯片 |
| **Marp Core** | 核心转换引擎，含内置主题 |
| **Marp CLI** | 命令行工具，导出 HTML/PDF/PPTX/图片 |
| **Marp for VS Code** | VS Code 扩展，实时预览 |
| **Obsidian Marp Plugin** | Obsidian 集成，预览和导出 |

---

## 2. Marpit 指令系统（Directives）

Marpit 通过"指令"扩展 Markdown，控制幻灯片的行为和样式。

### 写法

**HTML 注释方式**：

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

**Front-matter 方式**：

```markdown
---
theme: default
paginate: true
---
```

### 全局指令（Global Directives）

作用于整个演示文稿，多次书写只认最后一个。

| 指令 | 说明 |
|------|------|
| `theme` | 指定主题 |
| `style` | 自定义 CSS（避免污染其他编辑器） |
| `headingDivider` | 按标题级别自动分页 |
| `lang` | 设置 HTML lang 属性 |

### 局部指令（Local Directives）

作用于**当前页及后续所有页**。

| 指令 | 说明 |
|------|------|
| `paginate` | 显示页码（true/false/hold/skip） |
| `header` | 页眉内容 |
| `footer` | 页脚内容 |
| `class` | 设置 `<section>` 的 CSS 类 |
| `backgroundColor` | 背景色 |
| `backgroundImage` | 背景图 |
| `backgroundPosition` | 背景位置（默认 center） |
| `backgroundRepeat` | 背景重复（默认 no-repeat） |
| `backgroundSize` | 背景大小（默认 cover） |
| `color` | 文字颜色 |

### Spot 指令（仅当前页）

在局部指令名前加 `_` 前缀，仅对当前页生效：

```markdown
<!-- _backgroundColor: black -->
<!-- _color: white -->
```

### 分页控制（paginate 的四种值）

| 值 | 显示页码 | 递增页码 |
|----|----------|----------|
| `true` | ✅ | ✅ |
| `false` | ❌ | ✅ |
| `hold` | ✅ | ❌ |
| `skip` | ❌ | ❌ |

### 标题自动分页（headingDivider）

```markdown
<!-- headingDivider: 2 -->

# 1st page
内容...

## 2nd page（h2 触发分页）
内容...

# 3rd page（h1 也触发分页）
```

数值表示"大于等于该级别的标题都会分页"，数组则只对指定级别生效。

---

## 3. 内置主题

Marp Core 提供三个内置主题：

| 主题 | 风格 |
|------|------|
| `default` | 经典白底，蓝灰色调 |
| `uncover` | 现代、极简、居中布局 |
| `gaia` | 彩色、大胆、左对齐 |

使用方式：

```markdown
---
marp: true
theme: uncover
---
```

### 自定义主题

创建 CSS 文件，使用 Marpit 的主题规范：

```css
/* @theme my-theme */
@import 'default';

section {
  background-color: #f5f5f5;
  color: #333;
}

h1 {
  color: #0066cc;
}
```

---

## 4. Marp CLI

### 安装

```bash
# npm
npx @marp-team/marp-cli@latest

# macOS
brew install marp-cli

# Windows (Scoop)
scoop install marp
```

### 基本用法

```bash
# 导出 HTML（默认）
marp presentation.md

# 导出 PDF
marp presentation.md --pdf

# 导出 PPTX
marp presentation.md --pptx

# 指定输出文件
marp presentation.md -o output.html

# 使用特定主题
marp --theme uncover --pdf presentation.md

# 导出后立即打开
marp presentation.md --pdf --open
```

> PDF/PPTX 导出需要系统安装 Chrome 或 Edge。

---

## 5. Obsidian Marp 插件

来源：<https://github.com/JichouP/obsidian-marp-plugin>

### 功能

- **预览**：点击侧边栏按钮或命令面板运行 `Marp: Open Preview`
- **自动重载**：保存文件后自动刷新预览
- **导出**：支持 PDF、PPTX、HTML（需要 Node.js）
- **图片嵌入**：支持 Wikilink（`![[image.png]]`）和 CommonMark（`![](image.png)`）格式
- **过渡效果**：HTML 导出支持页面过渡动画

### 设置

| 设置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| Enable Auto Reload | toggle | on | 保存时自动刷新预览 |
| Open Preview in Split Tab | toggle | on | 在分栏中打开预览 |
| Theme Folder Location | text | `MarpTheme` | 自定义主题 CSS 目录 |

### 自定义主题

```
<your-vault>
└── MarpTheme/
    ├── beamer.css
    ├── border.css
    └── gradient.css
```

> 添加 CSS 后需要重启 Obsidian。

### 图片处理

导出时图片自动转为 Base64 嵌入，支持本地图片分享。路径支持：

- Wikilink：`![[path/to/image.png]]`
- CommonMark：`![alt](path/to/image.png)`
- 绝对路径和相对路径（相对于 vault 根目录）

---

## 6. 最小可运行示例

```markdown
---
marp: true
theme: uncover
paginate: true
---

# 我的第一个 Marp 幻灯片

用 Markdown 写演示文稿

---

## 第二页

- 项目一
- 项目二
- 项目三

---

## 第三页

> 就这么简单！

<!-- _backgroundColor: #1a1a2e -->
<!-- _color: #e0e0e0 -->

# 深色背景页

这段文字是浅色的
```