llm_wiki/raw/marp-guide.md

title, source, author, created, description, tags, rating

title	source	author	created	description	tags	rating
Marp 学习资料汇编	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/	Marp Team JichouP Samuele Cozzi	2026-04-07	Marp 生态系统学习资料汇编：Marpit 框架、Marp CLI、Obsidian Marp 插件	clippings marp presentation obsidian	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 注释方式：

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

Front-matter 方式：

---
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 指令（仅当前页）

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

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

分页控制（paginate 的四种值）

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

标题自动分页（headingDivider）

<!-- headingDivider: 2 -->

# 1st page
内容...

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

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

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

---

3. 内置主题

Marp Core 提供三个内置主题：

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

使用方式：

---
marp: true
theme: uncover
---

自定义主题

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

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

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

h1 {
  color: #0066cc;
}

---

4. Marp CLI

安装

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

# macOS
brew install marp-cli

# Windows (Scoop)
scoop install marp

基本用法

# 导出 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. 最小可运行示例

---
marp: true
theme: uncover
paginate: true
---

# 我的第一个 Marp 幻灯片

用 Markdown 写演示文稿

---

## 第二页

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

---

## 第三页

> 就这么简单！

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

# 深色背景页

这段文字是浅色的