---
categories:
  - "[[Marp]]"
tags:
  - marp
  - syntax
  - directives
created: 2026-04-07
source: "[[marp-guide]]"
type: reference
aliases:
  - Marp 指令
  - Marpit 指令
---

# Marp 指令语法

> Marp 通过**指令（Directives）**扩展 Markdown，控制幻灯片的主题、分页、页眉页脚、背景等。

## 写法

两种写法，效果相同：

**Front-matter**（推荐，放在文件最开头）：

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

**HTML 注释**（可放在任意位置）：

```markdown
<!--
theme: uncover
paginate: "true"
-->
```

> [!tip] 推荐用 front-matter 写全局指令，HTML 注释写局部指令。注意 front-matter 中的布尔值需用引号包裹（如 `"true"`），避免 Obsidian 将其识别为 checkbox 属性。

## 全局指令

作用于整个演示文稿。重复书写只认最后一个。

| 指令 | 说明 | 示例 |
|------|------|------|
| `theme` | 主题名称 | `theme: uncover` |
| `style` | 自定义 CSS | `style: \|` 后跟 CSS 块 |
| `headingDivider` | 标题自动分页 | `headingDivider: 2` |
| `lang` | HTML lang 属性 | `lang: zh-CN` |

## 局部指令

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

| 指令 | 说明 | 示例 |
|------|------|------|
| `paginate` | 页码 | `paginate: "true"` |
| `header` | 页眉 | `header: '演示标题'` |
| `footer` | 页脚 | `footer: '作者名'` |
| `class` | CSS 类名 | `class: lead` |
| `backgroundColor` | 背景色 | `backgroundColor: #1a1a2e` |
| `backgroundImage` | 背景图 | `backgroundImage: url(…)` |
| `backgroundPosition` | 背景位置 | `backgroundPosition: center` |
| `backgroundRepeat` | 背景重复 | `backgroundRepeat: no-repeat` |
| `backgroundSize` | 背景大小 | `backgroundSize: cover` |
| `color` | 文字颜色 | `color: white` |

## Spot 指令（仅当前页）

在局部指令名前加 `_` 前缀，效果**仅限当前页**：

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

这一页黑底白字，下一页恢复原样。

## paginate 的四种模式

| 值 | 显示页码 | 递增计数 | 场景 |
|----|----------|----------|------|
| `true` | ✅ | ✅ | 正常显示 |
| `false` | ❌ | ✅ | 隐藏但计数 |
| `hold` | ✅ | ❌ | 显示但不递增 |
| `skip` | ❌ | ❌ | 完全跳过 |

> [!tip] 跳过标题页的页码：把 `paginate: "true"` 放在第二页而不是第一页。

## 标题自动分页（headingDivider）

让标题自动触发分页，不需要手动写 `---`：

```markdown
---
headingDivider: 2
---

# 第一页
内容

## 第二页（h2 自动分页）
内容

# 第三页（h1 也分页，因为 1 < 2）
内容
```

- 数值 `2`：h1 和 h2 都会分页（"大于等于该级别"）
- 数组 `[2, 4]`：只有 h2 和 h4 会分页

> [!warning] `headingDivider` 设置后，`---` 分页线仍然可用，两者共存。

## 页眉页脚

```markdown
---
header: '**我的演示**'
footer: '作者名 · 2026'
paginate: "true"
---
```

页眉页脚支持 Markdown 格式（加粗、斜体、图片），但不支持 `![bg]()` 语法。

## 来源

- [[marp-guide]] — 原始资料
- [[Marp]] — Marp 概念页