MarsDawn

給 AI agent 的 marsdawn 參考

給呼叫 marsdawn 命令列工具的 AI agent 與腳本參考。本頁每個範例都用目前原始碼建置的工具實際執行過。

要把 Markdown 檔轉成 PDF，執行 marsdawn export notes.md --json，再從 stdout 讀取一個 JSON 物件。Mermaid 圖表與程式碼上色的呈現方式和 MarsDawn app 相同。export 不需要 app，open 需要。

能做什麼

不做什麼

export

marsdawn export notes.md --json

在 notes.md 旁寫出 notes.pdf。選項：

marsdawn export notes.md -o out.pdf --theme classic --paper letter --force --json

成功，離開代碼 0：

{"diagramErrors":[],"ok":true,"output":"/path/to/out.pdf","pages":1,"paper":"letter","theme":"classic"}

open

marsdawn open notes.md --json
marsdawn open notes.md:120 --json
marsdawn open notes.md --line 120 --json
marsdawn open . --json
marsdawn open notes.md --folder . --background --json

成功，離開代碼 0：

{"app":"/Applications/MarsDawn.app","ok":true,"opened":[{"line":120,"path":"/path/to/notes.md"}]}

有資料夾時（marsdawn 0.5.1 以後），離開代碼 0：

{"app":"/Applications/MarsDawn.app","folder":{"path":"/path/to/project","requested":true},"ok":true,"opened":[{"path":"/path/to/project/notes.md"}]}

marsdawn 0.2.x 的 opened 是路徑字串的清單。如果需要同時處理兩種格式，請先查看 marsdawn --version。

在 Claude Code 編輯時開啟檔案

一個需要自行啟用的 Claude Code hook：Claude 寫入或編輯 Markdown 檔案之後，在背景用 MarsDawn 開啟那個檔案，每個 session 每個檔案只開一次。除非你加上它，否則不會啟用，而且要一個專案一個專案加，因為你沒要求就跳出來的視窗會打斷注意力。它執行的是 shell 指令，不花模型 token。

需要 marsdawn 0.5.1 或更新版本，才有 --background，以及 MarsDawn app。

把下面的內容存成專案裡的 .claude/hooks/marsdawn-open.sh，再用 chmod +x 讓它可以執行：

#!/bin/sh
# Claude Code PostToolUse hook: open a Markdown file Claude just wrote or edited in MarsDawn,
# in the background, once per file per session. Never blocks Claude: every path exits 0.
input=$(cat)
file=$(printf '%s' "$input" | /usr/bin/jq -r '.tool_input.file_path // empty' 2>/dev/null)
session=$(printf '%s' "$input" | /usr/bin/jq -r '.session_id // "unknown"' 2>/dev/null)

case "$file" in
  *.md|*.markdown) ;;
  *) exit 0 ;;
esac
[ -f "$file" ] || exit 0
# A hook runs with Claude Code's PATH, which may not include Homebrew's.
marsdawn=$(command -v marsdawn || { [ -x /opt/homebrew/bin/marsdawn ] && echo /opt/homebrew/bin/marsdawn; }) || exit 0
[ -n "$marsdawn" ] || exit 0

# One list per session, so a file opens once however often Claude edits it.
seen="${TMPDIR:-/tmp}/marsdawn-hook/$session"
mkdir -p "$(dirname "$seen")"
grep -qxF "$file" "$seen" 2>/dev/null && exit 0
echo "$file" >> "$seen"

"$marsdawn" open --background "$file" >/dev/null 2>&1 || true
exit 0

然後把 hook 加到專案的 .claude/settings.json；如果只想自己用，改加到 .claude/settings.local.json：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/marsdawn-open.sh" }
        ]
      }
    ]
  }
}

失敗

加上 --json 時，失敗會在 stdout 輸出一個 JSON 物件，並以對應的代碼結束：

{"error":"output_exists","message":"/path/to/notes.pdf already exists. Pass --force to replace it.","ok":false}

JSON Schema

每種 --json 結果的 JSON Schema（draft 2020-12）：

環境變數

系統需求

安裝

使用 Homebrew。在 Apple 晶片的 Mac 上，會直接安裝預先建置好的版本，幾秒就完成，不需要 Xcode。在 Intel Mac 上則會從原始碼編譯 marsdawn，需要幾分鐘，也需要 Xcode 26 以上。

brew tap redtear1115/tap && brew install marsdawn
marsdawn --version

也可以從原始碼建置。第一次建置會下載相依套件並編譯，同樣需要幾分鐘。

git clone https://github.com/redtear1115/mars-dawn-kit.git
cd mars-dawn-kit
swift build -c release --product marsdawn
.build/release/marsdawn export notes.md --json

marsdawn --version 會印出版本號，例如 0.3.0，並以代碼 0 結束。

接下來