283 lines
5.3 KiB
Markdown
283 lines
5.3 KiB
Markdown
---
|
||
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（``）格式
|
||
- **过渡效果**：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：``
|
||
- 绝对路径和相对路径（相对于 vault 根目录）
|
||
|
||
---
|
||
|
||
## 6. 最小可运行示例
|
||
|
||
```markdown
|
||
---
|
||
marp: true
|
||
theme: uncover
|
||
paginate: true
|
||
---
|
||
|
||
# 我的第一个 Marp 幻灯片
|
||
|
||
用 Markdown 写演示文稿
|
||
|
||
---
|
||
|
||
## 第二页
|
||
|
||
- 项目一
|
||
- 项目二
|
||
- 项目三
|
||
|
||
---
|
||
|
||
## 第三页
|
||
|
||
> 就这么简单！
|
||
|
||
<!-- _backgroundColor: #1a1a2e -->
|
||
<!-- _color: #e0e0e0 -->
|
||
|
||
# 深色背景页
|
||
|
||
这段文字是浅色的
|
||
```
|