135 lines
3.1 KiB
Markdown
135 lines
3.1 KiB
Markdown
---
|
||
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 概念页
|