從 Markdown 到簡報：完全在終端裡製作投影片

問題：簡報是生產力的墳場

星期天晚上十一點。明天要上台。內容其實都有了 -- 散落在研究筆記、設計文件、也許還有一篇部落格草稿裡。難的不是要講什麼。難的是你接下來要浪費的那兩個小時，跟 PowerPoint 搏鬥。

你把文字方塊往右拖三個像素。復原。拖兩個像素。你跟那個彷彿對你有私人恩怨的項目符號縮排纏鬥。你捲過四十七種投影片切換效果，每一個都比上一個更讓人分心，最後選了「無」-- 這十秒前就該選了。

然後共同講者要求修改。你打開 deck_final_v3_真的最終版.pptx，改完寄給三個人。現在有四份副本，像平行宇宙一樣各自發散，永遠不會合流。沒有 diff。沒有 merge。沒有歷史紀錄。只有披著 .pptx 副檔名的混亂。

簡報有三個問題：版本控制、工具、內容結構。三個都能用終端裡現有的工具解決。

這樣想。你不會用所見即所得編輯器寫程式、把 .js 檔用 email 寄給團隊、用檔名後綴追蹤版本。那太瘋了。但大多數人做簡報就是這樣。

這篇文章示範完整的替代方案：用 Markdown 寫投影片、用 Claude Code 組織內容和產生講者備註、用 Marp CLI 輸出 PDF/HTML/PPTX、編輯時即時預覽、所有修改都在 git 裡追蹤。

技術棧：Marp CLI + Claude Code + Git

簡報 workflow 靠三根柱子。每個做一件事。合起來取代 PowerPoint 的一切功能 -- 減掉挫折感。

Marp CLI（@marp-team/marp-cli）是轉換器。餵它一個 Markdown 檔，它產出投影片。每個 --- 分隔符號就是一張新投影片。它能輸出 PDF、HTML 和 PPTX。支援主題、自訂 CSS、背景圖片和講者備註。殺手級功能是 --watch 模式：改原始檔，輸出立刻重新產生。想像成簡報的 hot-reload。

Claude Code 處理智力勞動 -- 手動做最花時間的那些事。它把零散筆記組織成連貫敘事、為每張投影片撰寫講者備註、執行最佳實踐：每張投影片一個概念、文字最少化、具體範例。它是你的簡報共同作者，不會累，也不會跟你爭字體大小。

Git 做 git 該做的事。追蹤每次修改、支援為不同聽眾開 branch、讓協作不再需要 deck_v4_john的修改.pptx。你的投影片變成程式碼。程式碼有 diff。Diff 有意義。

安裝

npm install -g @marp-team/marp-cli

就這樣。Claude Code 和 git 你的機器上已經有了。

第一步：把原始內容組織成投影片

從你的原始素材開始。腦力激盪的筆記、文件大綱、現有的部落格文章、甚至語音備忘錄的逐字稿。全倒進一個檔案 -- 潤飾是後面的事。

cat > raw-notes.md << 'EOF'
主題：為什麼工程團隊應該採用 Git Worktrees

重點：
- 分支間的上下文切換會摧毀心流狀態
- git worktree 從一個 repo 建立平行的工作目錄
- 每個 worktree 有自己的 HEAD、index、工作樹
- 搭配 AI CLI agent 可以實現真正的平行開發
- 設定只要 5 分鐘，每週省下好幾個小時
- 導入門檻低：只是一個新的 git 指令

目標聽眾：工程主管、資深開發者
簡報時長：10-15 分鐘
EOF

讓 Claude Code 把這堆條列轉成 Marp 格式的投影片。Prompt 很具體 -- 告訴 agent 格式、限制條件、講者備註的品質標準。

claude -p "
Read raw-notes.md. Create a Marp-formatted presentation in slides.md.

Rules:
- Use '---' to separate slides. First slide is the title slide.
- Add 'marp: true' in the YAML frontmatter.
- One core idea per slide. Maximum 5 bullet points per slide.
- Include speaker notes under each slide using Marp comment syntax.
- Write speaker notes as if coaching the presenter: what to emphasize, where to pause, what question the audience might ask.
- Target 12-15 slides for a 10-15 minute talk.
- End with a clear call-to-action slide and a Q&A slide.
"

Claude Code 讀取原始筆記、理解主題結構、產出完整的 Marp 檔案。輸出長這樣：

---
marp: true
theme: default
paginate: true
---

# Git Worktrees：無痛的平行開發

**工程生產力系列**
Danny Huang | 2026 年 3 月

<!-- speaker notes: 用一個問題開場：「這週大家 git stash 了幾次？」讓他們想一下。多數人會說 3-5 次。這就是你要解決的痛點。 -->

---

## 上下文切換的代價

- 開發者平均每天切換分支 **5-10 次**
- 每次切換：stash、checkout、重建、重新定位
- 中斷後需要 **15-25 分鐘**才能恢復深度專注
- 5 次切換 x 20 分鐘 = **每天損失約 2 小時**

<!-- speaker notes: 這些數據來自微軟研究院的開發者生產力研究。在「2 小時」這個數字後停頓一下，讓它沉澱。會有人明顯有反應。 -->

---

## 如果你再也不用切分支呢？

```bash
git worktree add ../feature-auth main
git worktree add ../hotfix-api release/2.1
```

兩個指令。兩個獨立的工作目錄。同一個 repository。

<!-- speaker notes: 這是「原來如此」的瞬間。秀終端畫面。如果可以就現場跑指令。聽眾需要親眼看到這有多簡單。 -->

---

注意講者備註在做什麼。它們不只是把項目符號唸出來。它們在教練：哪裡停頓、預期什麼反應、要不要現場 demo。這就是你真的會用的備註和直接跳過的備註之間的差異。

第二步：在 CLAUDE.md 設定簡報風格

好的簡報風格就像好的 coding style guide。定義一次，之後每份投影片自動遵循同樣的規則。

在專案的 CLAUDE.md 加入簡報區段。這告訴 Claude Code 怎麼做每一份投影片 -- 你把品味編碼一次，agent 永遠幫你執行。

## Presentation Style Guidelines

### Slide Content
- One idea per slide. If you need a second idea, make a second slide.
- Maximum 5 bullet points. Prefer 3.
- Every slide must pass the "squint test": readable from the back of the room.
- No full sentences on slides. Fragments and keywords only.
- Code blocks: maximum 6 lines. Highlight the one line that matters.

### Speaker Notes
- Write for a nervous presenter, not a confident one.
- Include: what to say, what to emphasize, what to skip if running short.
- Note likely audience questions and suggested answers.
- Mark optional slides with [SKIP IF SHORT].

### Structure
- Slide 1: Title + speaker credibility (one line).
- Slide 2: The problem. Make the audience feel the pain.
- Slides 3-N: The solution, building incrementally.
- Slide N-1: Concrete call-to-action. Not "learn more" -- a specific next step.
- Slide N: Q&A with 2-3 pre-loaded questions the presenter can seed.

### Visual Direction
- Marp theme: default or gaia.
- Use Marp backgroundColor directive for emphasis slides.
- One image per slide maximum. Images must earn their place.

把 CLAUDE.md 想成簡報的 style.config。你不會讓團隊每個人自己選 linting 規則。同樣的道理。定義一次規則，讓 agent 每次幫你執行。

第三步：用 Marp CLI 輸出和預覽

Marp CLI 把你的 Markdown 轉換成簡報格式。一個指令一種格式。

# 輸出 HTML（最快，適合預覽）
marp slides.md -o slides.html

# 輸出 PDF（用於散佈）
marp slides.md -o slides.pdf

# 輸出 PowerPoint（給需要 pptx 的組織）
marp slides.md -o slides.pptx

真正的威力在 --watch 模式。它監控 Markdown 檔案，每次存檔就自動重新產生輸出 -- 就像投影片的 live-reload server。

marp slides.md -o slides.html --watch

這會開啟一個瀏覽器視窗，即時更新。每次存檔 Markdown，瀏覽器在一秒內重新整理。你在編輯器裡打字的同時，就能看到聽眾將看到的畫面。不用按「預覽」按鈕。不用等 build 步驟。存檔就看到。

第四步：即時編輯循環

這裡是 workflow 不再像工作、開始像超能力的地方。

開兩個並排的終端面板。左面板：你的編輯器（vim、neovim、nano，用你習慣的任何工具）開著 slides.md。右面板：執行 marp slides.md -o slides.html --watch，HTML 輸出在瀏覽器中開啟。

在左面板編輯一張投影片。存檔。右面板瞬間更新。你不用切換視窗、不用按「預覽」、不用等任何東西。這是簡報者能擁有的最緊密回饋循環 -- 比任何 GUI 工具都緊，因為你的想法和輸出之間只隔一個按鍵。

需要重新組織某個段落？問 Claude Code。

claude -p "
Read slides.md. Slides 5-8 cover git worktree internals. They are too detailed
for this audience (engineering leads, not kernel developers). Condense slides
5-8 into two slides: one covering the mental model, one covering the three
commands they need. Update speaker notes accordingly. Write the result back
to slides.md.
"

存檔。右面板更新。你立刻看到精簡後的版本。回饋循環以秒計算，不是分鐘。

第五步：批次產生講者備註

這個場景不斷發生：你有投影片但沒有講者備註。也許趕工做的。也許從現有簡報匯入的。也許你是那種「我到時候即興」然後在台上後悔的人。

Claude Code 可以一次為所有投影片產生或升級備註。

claude -p "
Read slides.md. For every slide that lacks speaker notes, generate them.

For every slide that already has speaker notes, review and improve them:
- Add timing estimates (e.g., 'spend 60 seconds here').
- Add transition phrases to the next slide.
- Note where to make eye contact, where to gesture at the screen.
- Flag slides that could be cut if the talk runs long.

Write the updated file back to slides.md.
"

手動為 15 張投影片寫好講者備註要 30-45 分鐘。Claude Code 一次搞定。而且因為它同時看到整份投影片的結構，寫出來的備註從頭到尾是連貫的 -- 轉場、呼應前面的重點、加總起來剛好符合目標時長。一個人逐張寫備註很少能達到這種連貫性。

第六步：建立可重複使用的簡報 Skill

如果你一季做超過一次簡報，把流程進一步自動化。存一個可重複使用的 skill 檔到專案的 .claude/skills/presentation-builder.md。

# Skill: Presentation Builder

## Trigger
When the user asks to create, edit, or restructure a presentation.

## Inputs
- Raw content file (notes, outline, blog post, or existing slides)
- Target audience
- Time constraint (e.g., "10 minutes", "lightning talk", "keynote")

## Process
1. Read the source material and identify the core narrative arc.
2. Structure into Marp-formatted slides following CLAUDE.md guidelines.
3. Generate speaker notes for every slide.
4. Add timing estimates that sum to the target duration.
5. Write output to slides.md (or specified filename).
6. Run `marp slides.md -o slides.html` to verify rendering.

## Output Format
- Marp-compatible Markdown with YAML frontmatter
- Speaker notes in HTML comment syntax
- One file, ready to render

## Quality Checks
- Total slide count reasonable for time constraint (~1 slide per minute)
- No slide has more than 5 bullet points
- Every slide has speaker notes
- Code blocks are under 6 lines
- Title slide includes speaker name and date

Skill 就像某個特定工作的 Makefile。有了它，以後做簡報只需要一個指令。Claude Code 讀取 skill 檔、遵循流程、產出可直接輸出的投影片。你從原始筆記到完整簡報，不需要每次重新說明流程。

第七步：簡報的版本控制

因為投影片是純 Markdown，git 完美適用。而這改變了一切。

git init presentations
cd presentations
git add slides.md
git commit -m "Initial deck: git worktrees for engineering leads"

現在你可以做 PowerPoint 根本做不到的事。

為不同聽眾開 branch。 同一份核心簡報，分別為工程師和主管客製化。就像維護一個 library，對不同使用者提供不同 API 介面。

git checkout -b audience/executives
claude -p "
Read slides.md. This version is for VP-level executives, not engineers.
Remove all code blocks. Replace technical details with business impact metrics.
Keep the narrative arc intact. Update speaker notes for a non-technical audience.
"
git add slides.md
git commit -m "Adapt deck for executive audience"

Diff 你的修改。 逐行精確看到兩個版本之間改了什麼。

git diff main..audience/executives -- slides.md

用 tag 標記版本。 再也不用猜哪場活動用的是哪個版本。

git tag "devcon-2026-march"

不複製檔案就能協作。 共同講者 clone repo、做修改、開 pull request。你 review diff。沒有 email 附件。沒有「到底哪個版本才是最新的？」就是你寫程式時已經在用的那套 workflow。

完整工作流腳本

一個腳本，從原始筆記到三種格式的可上台簡報。

#!/bin/bash
set -euo pipefail

SOURCE="${1:?用法: ./build-deck.sh <notes-file>}"
DECK="slides.md"
OUTPUT_DIR="./dist"

mkdir -p "$OUTPUT_DIR"

echo "[1/4] 將內容組織成投影片..."
claude -p "
Read $SOURCE. Create a Marp-formatted presentation in $DECK.
Follow all rules in CLAUDE.md under 'Presentation Style Guidelines'.
Include speaker notes for every slide.
"

echo "[2/4] 輸出所有格式..."
marp "$DECK" -o "$OUTPUT_DIR/slides.html" &
marp "$DECK" -o "$OUTPUT_DIR/slides.pdf" &
marp "$DECK" -o "$OUTPUT_DIR/slides.pptx" &
wait

echo "[3/4] 提交到 git..."
git add "$DECK"
git commit -m "Generate deck from $(basename "$SOURCE")"

echo "[4/4] 完成。輸出："
echo "  $DECK                      -- 原始檔（可編輯）"
echo "  $OUTPUT_DIR/slides.html    -- 瀏覽器預覽"
echo "  $OUTPUT_DIR/slides.pdf     -- 用於散佈"
echo "  $OUTPUT_DIR/slides.pptx    -- 給 PowerPoint 使用者"
echo ""
echo "開始即時編輯："
echo "  marp $DECK -o $OUTPUT_DIR/slides.html --watch"

執行：

chmod +x build-deck.sh
./build-deck.sh raw-notes.md

從原始筆記到三種格式的簡報輸出，已 commit 到 git。30 秒內。這不是誇飾 -- 瓶頸是 AI 呼叫，而那也在你咖啡涼掉之前就跑完了。

為什麼這比 GUI 工作流好

想像兩個平行宇宙。

宇宙 A，你打開 PowerPoint。手動建投影片。跟排版搏鬥一小時。存成 deck_v1.pptx。Email 給共同講者。收到 deck_v1_修改版.pptx。手動 merge 修改，祈禱你沒漏掉任何編輯。搞不清楚哪個版本才是「真的那個」。

宇宙 B，你寫 Markdown。AI agent 處理結構和講者備註。一個指令輸出任何格式。Git 追蹤每次修改。Branch 處理不同聽眾。Diff 精確顯示改了什麼。Pull request 取代 email 附件。

差距會隨時間複利成長。

最大的贏面是講者備註。大多數人跳過它們，因為寫備註太無聊 -- 跟寫文件一樣，大家都同意很重要但沒人想做。有了 Claude Code 產生的備註 -- 包含計時、轉場語、聽眾覺察提示、超時應變方案 -- 即使是第一次上台的人也有內建的演講教練。

多面板配置

理想的編輯配置用三個面板，各自負責一件事。左面板：你的文字編輯器開著 slides.md。右上面板：Claude Code 用於結構調整和講者備註產生。右下面板：marp --watch 搭配瀏覽器顯示即時輸出。

你在左邊編輯內容。在右上要求 Claude Code 重組段落或精修備註。在右下即時看到渲染結果更新。三個面板、一個 workflow、應用程式之間零上下文切換。就像有一個寫作夥伴和一個設計預覽坐在你旁邊，你一完成想法他們就同步更新。

審查完成的簡報時，兩個面板就夠：左邊是 Markdown 原始碼，右邊是渲染後的 HTML。同時捲動兩邊。你會抓出只有在渲染輸出中才會出現的排版問題 -- 溢出的程式碼區塊、條列太多的投影片、換行很醜的標題。

總結

簡報就是文件。文件就該做版本控制。內容組織和講者備註撰寫正好是 AI agent 擅長的任務：按照明確規則把想法機械性地轉換成結構化格式。人類不擅長這些不是因為難，而是因為無聊。Agent 不會無聊。

技術棧很簡單。Marp CLI 把 Markdown 渲染成投影片。Claude Code 組織內容、撰寫講者備註。Git 追蹤一切。一個可重複使用的 skill 檔意味著以後做簡報只需要一份原始筆記和一個指令。

別再跟投影片排版工具搏鬥了。寫 Markdown。讓終端處理剩下的事。