Marp 完整教學

1. 專案定位與核心價值

什麼是 Marp？

Marp（Markdown Presentation Ecosystem）是一個以純 Markdown 撰寫簡報的完整生態系。它的核心理念是「內容與樣式分離（Separation of Content and Style）」——你只需要專注於簡報的文字內容與邏輯結構，視覺呈現則交由 CSS 主題系統處理。

為什麼選擇 Marp？

傳統簡報工具	Marp
拖拉排版，容易花大量時間調整格式	純文字撰寫，專注內容
檔案格式封閉（.pptx），版控困難	純 Markdown，完美配合 Git 版控
團隊成員樣式不一致	CSS 主題統一視覺風格
手動匯出多種格式	CLI 一鍵轉換 HTML / PDF / PPTX
難以自動化	完美整合 CI/CD pipeline

核心價值

版控友好：Markdown 純文字，可以 git diff 追蹤每一處修改
可重現性：同一份 .md 在任何環境產出一致的簡報
自動化：搭配 Marp CLI 可在 CI/CD 中自動產生簡報
可擴充：基於 Marpit 框架的可插拔架構，支援 markdown-it 外掛
零鎖定：即使不用 Marp，你的 Markdown 檔案仍然是可讀的文件

2. 安裝與環境設定

方式一：Marp for VS Code（推薦新手）

安裝 Visual Studio Code
在 VS Code 擴充套件市集搜尋並安裝 Marp for VS Code
建立新的 .md 檔案
在編輯器工具列點選 Marp 圖示，啟用 Marp 功能（自動加入 front matter）
開啟 VS Code Markdown 預覽，即可開始撰寫

方式二：Marp CLI

macOS（Homebrew）

1brew install marp-cli

Windows（Scoop）

1scoop install marp

Node.js（免安裝一次性轉換）

1npx @marp-team/marp-cli@latest your-slides.md

Node.js 專案安裝

1# npm
2npm install --save-dev @marp-team/marp-cli
3
4# yarn
5yarn add --dev @marp-team/marp-cli

Docker

1docker pull marpteam/marp-cli
2docker run --rm -v $(pwd):/home/marp marpteam/marp-cli your-slides.md

獨立二進位檔

從 GitHub Releases 下載對應平台的執行檔。

CLI vs VS Code 選擇指南

功能	Marp for VS Code	Marp CLI
編輯器	VS Code	任意編輯器
即時預覽	有	有（`--preview`）
匯出方式	點擊匯出	命令列
使用外掛	不支援	支援
CI/CD 整合	不適用	完美支援
批次處理	不支援	支援

3. 核心架構解析

Marp 生態系架構

Marp 並非單一工具，而是由多個專注於特定功能的子專案組成的生態系：


graph TD
    subgraph "Marp Ecosystem"
        direction TB
        MARPIT["Marpit Framework
底層 slide deck 框架"]
        CORE["Marp Core
內建主題 + 實用功能"]
        CLI["Marp CLI
命令列轉換工具"]
        VSCODE["Marp for VS Code
VS Code 擴充套件"]
        PLUGINS["markdown-it Plugins
社群擴充外掛"]
    end

    subgraph "Input"
        MD["Markdown (.md)"]
        CSS["Theme CSS (.css)"]
        CONFIG["Config (marp.config.js)"]
    end

    subgraph "Output"
        HTML["HTML"]
        PDF["PDF"]
        PPTX["PPTX"]
        IMG["PNG / JPEG"]
    end

    MD --> MARPIT
    CSS --> MARPIT
    MARPIT --> CORE
    PLUGINS --> CORE
    CORE --> CLI
    CORE --> VSCODE
    CONFIG --> CLI
    CLI --> HTML
    CLI --> PDF
    CLI --> PPTX
    CLI --> IMG
    VSCODE --> HTML
    VSCODE --> PDF
    VSCODE --> PPTX

各層職責

層級	元件	職責
Framework	Marpit	最底層框架：Markdown 解析、slide 分割、directive 系統、image syntax、CSS 主題引擎
Core	Marp Core	在 Marpit 之上加入實用功能：內建主題（default / gaia / uncover）、數學排版、emoji、語法高亮
App	Marp CLI	命令列介面：檔案轉換、watch mode、server mode、自訂引擎、外掛載入
App	Marp for VS Code	圖形化介面：即時預覽、語法補全、匯出指令

轉換流程


flowchart LR
    A["Markdown 原始檔"] --> B["Marpit 解析
（directives + slide 分割）"]
    B --> C["Marp Core 處理
（主題 + 數學 + emoji）"]
    C --> D["HTML 中間產物"]
    D --> E{"匯出格式"}
    E -->|"直接"| F["HTML"]
    E -->|"Chromium 渲染"| G["PDF"]
    E -->|"Chromium 渲染"| H["PPTX"]
    E -->|"Chromium 截圖"| I["PNG / JPEG"]

PDF、PPTX、圖片匯出需要本機安裝 Chromium 系瀏覽器（Chrome / Edge）。

4. 主要功能詳解

4.1 Slide 分割

使用水平分隔線 --- 將 Markdown 分割為多張投影片：

1# 第一張投影片
2
3Hello, world!
4
5---
6
7# 第二張投影片
8
9Marp 用水平分隔線分割投影片。

也可使用 ___、***、- - - 作為分割符號（避免 CommonMark 要求前後空行的問題）。

4.2 Directives（指令）

Directives 是 Marp 的擴充語法，用於控制主題、頁碼、頁首頁尾等元素。

Global Directives（全域指令）

在 front matter 或 HTML 註解中定義，作用於整份簡報：

1---
2marp: true
3theme: default
4paginate: true
5headingDivider: 2
6size: 16:9
7math: mathjax
8---

指令	說明
`theme`	設定主題（default / gaia / uncover / 自訂）
`style`	嵌入 CSS 微調主題
`headingDivider`	依標題層級自動分割投影片
`size`	投影片尺寸（4:3 / 16:9）
`math`	數學排版引擎（mathjax / katex）
`marp`	在 VS Code 中啟用 Marp

Local Directives（區域指令）

在 HTML 註解中定義，作用於當前投影片及後續投影片：

1<!-- paginate: true -->
2<!-- header: "我的簡報" -->
3<!-- footer: "第 X 頁" -->
4<!-- backgroundColor: lightblue -->
5<!-- color: darkblue -->

Scoped Directives（限定範圍指令）

加上底線前綴 _，僅作用於當前投影片：

1<!-- _backgroundColor: #ff6347 -->
2<!-- _color: white -->

4.3 Heading Divider（標題分割）

自動依標題層級分割投影片，特別適合將既有 Markdown 文件轉為簡報：

 1---
 2marp: true
 3headingDivider: 2
 4---
 5
 6# 大主題
 7
 8概述內容
 9
10## 子題一
11
12子題一的內容
13
14## 子題二
15
16子題二的內容

4.4 Fitting Header（自適應標題）

使用  讓標題自動縮放填滿投影片寬度：

1# <!-- fit --> 這個標題會自動縮放

搭配 headingDivider 可快速製作 Takahashi 風格簡報（每頁只有一個大字）。

4.5 Image Syntax（圖片語法）

Marp 擴充了 Markdown 圖片語法，支援尺寸控制與背景設定：

 1<!-- 設定寬度 -->
 2![w:300](image.png)
 3
 4<!-- 設定高度 -->
 5![h:200](image.png)
 6
 7<!-- 同時設定 -->
 8![w:300 h:200](image.png)
 9
10<!-- 設為背景圖 -->
11![bg](background.jpg)
12
13<!-- 背景圖分割模式 -->
14![bg left](side-image.jpg)

4.6 Fragmented List（漸進式清單）

使用 * 標記（而非 -）建立漸進式清單（僅 HTML 匯出有效）：

1<!-- 一般清單 -->
2- 項目一
3- 項目二
4
5<!-- 漸進式清單 -->
6* 項目一
7* 項目二

4.7 數學排版

支援 MathJax（預設）與 KaTeX：

 1---
 2math: mathjax
 3---
 4
 5行內公式：$E = mc^2$
 6
 7區塊公式：
 8
 9$$
10\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
11$$

4.8 內建主題

主題	風格
`default`	經典白底簡報
`gaia`	深色系現代風格
`uncover`	簡潔無襯線風格

每個主題都支援 class: invert 切換深 / 淺色模式。

5. 應用場景與實戰範例

場景一：技術簡報快速產出

 1---
 2marp: true
 3theme: default
 4paginate: true
 5---
 6
 7# API 設計原則
 8
 9RESTful API Best Practices
10
11---
12
13## 命名慣例
14
15- 使用複數名詞：`/users`、`/orders`
16- 巢狀資源：`/users/{id}/orders`
17- 動作用動詞：`/users/{id}/activate`
18
19---
20
21## HTTP 方法對應
22
23| 方法 | 用途 | 冪等性 |
24|------|------|--------|
25| GET | 讀取 | 是 |
26| POST | 建立 | 否 |
27| PUT | 完整更新 | 是 |
28| PATCH | 部分更新 | 否 |
29| DELETE | 刪除 | 是 |

場景二：CI/CD 自動產生簡報

 1# .github/workflows/slides.yml
 2name: Build Slides
 3on:
 4  push:
 5    paths: ['slides/**']
 6
 7jobs:
 8  build:
 9    runs-on: ubuntu-latest
10    steps:
11      - uses: actions/checkout@v4
12      - run: npx @marp-team/marp-cli@latest slides/*.md -o output/ --pdf
13      - uses: actions/upload-artifact@v4
14        with:
15          name: slides-pdf
16          path: output/

場景三：學術研究報告

 1---
 2marp: true
 3theme: default
 4math: mathjax
 5paginate: true
 6header: "研究進度報告 2026-Q2"
 7---
 8
 9# 蛋白質結構預測
10
11AlphaFold3 整合分析
12
13---
14
15## 方法
16
17使用 AlphaFold3 multimer mode 預測：
18
19$$
20\text{pLDDT} = \frac{1}{N} \sum_{i=1}^{N} \text{confidence}_i
21$$
22
23---
24
25## 結果摘要
26
27| 目標蛋白 | pLDDT | ipTM |
28|----------|-------|------|
29| Target A | 89.2  | 0.85 |
30| Target B | 76.5  | 0.72 |

場景四：團隊標準化模板

建立 marp.config.js 統一團隊簡報風格：

1// marp.config.js
2module.exports = {
3  allowLocalFiles: true,
4  themeSet: './themes',
5  options: {
6    looseYAML: false,
7    math: { lib: 'mathjax' },
8  },
9}

搭配自訂主題 CSS：

 1/* themes/company.css */
 2/* @theme company */
 3
 4section {
 5  font-family: 'Noto Sans TC', sans-serif;
 6  background-color: #ffffff;
 7  color: #333333;
 8}
 9
10section.lead {
11  background-color: #003366;
12  color: #ffffff;
13}
14
15header, footer {
16  font-size: 0.6em;
17  color: #999999;
18}

6. 資安掃描報告

掃描結果：🟢 Low Risk

項目	結果
惡意程式碼（eval / exec / subprocess）	未偵測到
硬編碼憑證（password / api_key / token / secret）	未偵測到
不安全的網路操作（curl / wget）	僅文件範例中出現 `curl`（下載展示用 Markdown），非程式碼邏輯
依賴風險	開發依賴僅限 eslint / prettier / typescript / lage
授權	MIT License，無限制

掃描細節

1website/blog/202205-ecosystem-update.md:185:  curl -o ./showcase.md ...
2  → 部落格文章中的示範指令，非自動執行程式碼
3
4website/docs/introduction/install.md:72:  npx (npm exec)
5  → 安裝說明文件，描述 npx 用法
6
7website/docs/introduction/install.md:87:  yarn exec
8  → 安裝說明文件，描述 yarn exec 用法

安全建議

本 repo 為入口倉庫，不含可執行後端程式碼，安全風險極低
Marp CLI 的 PDF/PPTX 匯出依賴 Chromium，建議在受控環境（Docker）中執行
HTML 匯出預設停用大部分 HTML 標籤，降低 XSS 風險
若啟用 --html 旗標允許全部 HTML 標籤，需注意使用者輸入的安全性

7. FAQ 常見問題

Q1：Marp 跟 reveal.js / Slidev 有什麼不同？

面向	Marp	reveal.js	Slidev
語法	純 Markdown + directives	HTML + Markdown 混合	Markdown + Vue 元件
學習曲線	極低	中等	中等（需懂 Vue）
自訂程度	CSS 主題 + 外掛	完全自訂	Vue 元件
匯出格式	HTML / PDF / PPTX / 圖片	HTML / PDF	HTML / PDF
CLI 支援	完整	需額外工具	有
適用場景	快速產出、CI/CD	互動式網頁簡報	Vue 開發者

Q2：PDF 匯出需要什麼環境？

Marp CLI 的 PDF / PPTX / 圖片匯出使用 Chromium 渲染引擎。需要本機安裝 Chrome、Chromium 或 Edge。Docker 環境已內建。

Q3：如何在 Marp 中使用自訂字型？

在主題 CSS 中使用 @import 或 @font-face：

1@import url('https://fonts.googleapis.com/css2?family=Noto+Sans+TC&display=swap');
2
3section {
4  font-family: 'Noto Sans TC', sans-serif;
5}

Q4：可以在投影片中嵌入影片嗎？

需要啟用 HTML 標籤支援（CLI 加 --html 旗標），然後使用 <video> 標籤：

1<video src="demo.mp4" controls width="80%"></video>

Q5：如何處理投影片內容溢出？

使用 headingDivider 自動分割過長內容
使用  讓標題自動縮放
調整 font-size 或使用 <style scoped> 針對單頁微調

8. 進階技巧

8.1 Watch Mode 即時預覽

1# 開啟瀏覽器即時預覽
2marp --preview your-slides.md
3
4# Watch mode（檔案變更自動重新轉換）
5marp -w your-slides.md -o output.html

8.2 Server Mode

1# 啟動本地伺服器
2marp -s ./slides-directory

8.3 多檔案批次轉換

1# 整個目錄轉換
2marp slides/ -o output/
3
4# 指定格式
5marp slides/*.md --pdf -o output/

8.4 自訂 Marpit Engine

1// engine.js
2const { Marp } = require('@marp-team/marp-core')
3const markdownItContainer = require('markdown-it-container')
4
5module.exports = (opts) => {
6  const marp = new Marp(opts)
7  marp.use(markdownItContainer, 'warning')
8  return marp
9}

1marp --engine ./engine.js your-slides.md

8.5 VS Code 工作區設定

1// .vscode/settings.json
2{
3  "markdown.marp.themes": [
4    "./themes/company.css"
5  ],
6  "markdown.marp.enableHtml": true
7}

8.6 Scoped Style 針對單頁調整

 1---
 2
 3<style scoped>
 4section {
 5  font-size: 0.8em;
 6}
 7table {
 8  font-size: 0.7em;
 9}
10</style>
11
12# 這頁有較多內容需要縮小字型
13
14| 大量 | 表格 | 資料 |

9. 整合進其他工作流

9.1 搭配 Git 版控

1project/
2├── slides/
3│   ├── weekly-report.md
4│   ├── tech-sharing.md
5│   └── themes/
6│       └── company.css
7├── marp.config.js
8├── .github/workflows/slides.yml
9└── output/          # .gitignore

9.2 搭配 Makefile

 1SLIDES := $(wildcard slides/*.md)
 2PDFS := $(SLIDES:slides/%.md=output/%.pdf)
 3
 4all: $(PDFS)
 5
 6output/%.pdf: slides/%.md
 7	npx @marp-team/marp-cli $< -o $@ --pdf --allow-local-files
 8
 9clean:
10	rm -rf output/
11
12.PHONY: all clean

9.3 搭配 Docker（無需本機安裝 Chromium）

1FROM marpteam/marp-cli:latest
2COPY slides/ /slides/
3WORKDIR /slides
4ENTRYPOINT ["marp", "--pdf", "--allow-local-files"]

1docker build -t my-slides .
2docker run --rm -v $(pwd)/output:/slides/output my-slides *.md -o output/

9.4 搭配 HyperFrames / 其他影片工具

Marp 匯出的 HTML 可作為 HyperFrames 的靜態場景來源，或透過 Puppeteer 截圖後製作影片素材。

9.5 搭配 AI Knowledge Template

1# 將研究 paper 的重點整理為簡報
2marp --theme default --pdf research-summary.md -o research-summary.pdf
3
4# 搭配 quarkdown 產生的教學內容
5# 先用 qd 產生完整教學 HTML，再用 Marp 產生精華簡報版

10. 重點摘要 Checklist

安裝 Marp CLI（brew install marp-cli）或 Marp for VS Code
在 Markdown 檔案開頭加入 marp: true front matter
使用 --- 分割投影片
設定 theme（default / gaia / uncover）與 paginate: true
善用 directives 控制頁首、頁尾、背景色
使用 headingDivider 自動分割長文件
使用  讓標題自適應
數學公式選擇 math: mathjax（推薦）或 katex
PDF / PPTX 匯出需要 Chromium 環境
團隊使用建議建立 marp.config.js + 自訂主題 CSS
CI/CD 整合推薦使用 Docker image marpteam/marp-cli

11. 進一步閱讀與參考資源

官方資源

Marp 官方網站 — 完整文件與指南
Marpit Framework 文件 — 底層框架 API 與語法
Marp CLI GitHub — CLI 工具原始碼與文件
Marp Core GitHub — 核心轉換引擎
Marp for VS Code — VS Code 擴充套件

社群資源

Awesome Marp — 社群精選主題、外掛、範例
Marp Discussion Forum — 官方討論區

學習資源

Markdown Guide — Markdown 基礎教學
Markdown Tutorial — 互動式 Markdown 練習

Marp 完整教學

Contents

Marp 完整教學

1. 專案定位與核心價值

什麼是 Marp？

為什麼選擇 Marp？

核心價值

2. 安裝與環境設定

方式一：Marp for VS Code（推薦新手）

方式二：Marp CLI

macOS（Homebrew）

Windows（Scoop）

Node.js（免安裝一次性轉換）

Node.js 專案安裝

Docker

獨立二進位檔

CLI vs VS Code 選擇指南

3. 核心架構解析

Marp 生態系架構

各層職責

轉換流程

4. 主要功能詳解

4.1 Slide 分割

4.2 Directives（指令）

Global Directives（全域指令）

Local Directives（區域指令）

Scoped Directives（限定範圍指令）

4.3 Heading Divider（標題分割）

4.4 Fitting Header（自適應標題）

4.5 Image Syntax（圖片語法）

4.6 Fragmented List（漸進式清單）

4.7 數學排版

4.8 內建主題

5. 應用場景與實戰範例

場景一：技術簡報快速產出

場景二：CI/CD 自動產生簡報

場景三：學術研究報告

場景四：團隊標準化模板

6. 資安掃描報告

掃描結果：🟢 Low Risk

掃描細節

安全建議

7. FAQ 常見問題

Q1：Marp 跟 reveal.js / Slidev 有什麼不同？

Q2：PDF 匯出需要什麼環境？

Q3：如何在 Marp 中使用自訂字型？

Q4：可以在投影片中嵌入影片嗎？

Q5：如何處理投影片內容溢出？

8. 進階技巧

8.1 Watch Mode 即時預覽

8.2 Server Mode

8.3 多檔案批次轉換

8.4 自訂 Marpit Engine

8.5 VS Code 工作區設定

8.6 Scoped Style 針對單頁調整

9. 整合進其他工作流

9.1 搭配 Git 版控

9.2 搭配 Makefile

9.3 搭配 Docker（無需本機安裝 Chromium）

9.4 搭配 HyperFrames / 其他影片工具

9.5 搭配 AI Knowledge Template

10. 重點摘要 Checklist

11. 進一步閱讀與參考資源

官方資源

社群資源

相關工具

學習資源

Related Posts

Comments