給 AI agent 的 marsdawn 參考

能做什麼

• export：用和 MarsDawn app 相同的匯出程式，把一個 Markdown 檔輸出成分頁的 PDF，不會開啟任何視窗。
• open：在 MarsDawn app 中開啟一或多個 Markdown 檔，讓人檢閱，也可以指定每個檔案要定位的行。

不做什麼

• 不從 stdin 讀取 Markdown，請傳入檔案路徑。
• 不把 PDF 寫到 stdout。PDF 一律寫成檔案，stdout 只輸出結果。
• 檔案已存在時不會覆寫，除非加上 --force。
• 不載入網路圖片，除非加上 --allow-remote-images，而且只走 https。
• 沒有安裝 MarsDawn 時，open 無法使用，會以代碼 3 結束。export 不需要 app。
• MarsDawn 1.0 還不會跳到 open 指定的行，會從檔案開頭顯示。
• 只能在 macOS 上執行。

export

marsdawn export notes.md --json

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

• -o, --output <path>：PDF 的寫入位置。預設為輸入檔路徑，副檔名換成 .pdf。
• --theme <dawn|classic|modern|vivid>：使用主題的淺色色盤。預設為 $MARSDAWN_THEME，其次是 dawn。
• --paper <a4|letter>：紙張大小。預設為 a4。
• --allow-remote-images：算繪時載入網路上的 https 圖片。
• --force：輸出檔已存在時覆寫。
• --json：在 stdout 輸出一個 JSON 物件，而不是文字。

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"}

• output：寫出的 PDF 的絕對路徑。
• pages：頁數。
• theme 與 paper：實際使用的值。
• diagramErrors：每個算繪失敗的 Mermaid 圖表各一則訊息。PDF 仍會寫出。

open

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

• path:line 指定要定位的行。後面再接欄位，例如 notes.md:120:8，會被忽略。如果參數本身就是一個存在的檔名，就一律當成那個檔案，所以名為 weird:12 的檔案會照原名開啟。
• --line <n> 為單一檔案指定行號，包括檔名本身以冒號加數字結尾的情況。只能搭配一個檔案。
• 行號範圍是 1 到 999999999，超出範圍是用法錯誤。
• 行號從 marsdawn 0.3.0 開始提供。MarsDawn 1.0 會打開檔案，但還不會跳到指定的行。

成功，離開代碼 0：

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

• opened：每個檔案一個物件，順序與傳入時相同。path 是檔案的絕對路徑；只有指定了行號時才有 line。
• app：開啟它們的 MarsDawn app 路徑。

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

失敗

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

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

• 2，input_not_found：輸入檔不存在、是資料夾，或不是 UTF-8 文字。
• 3，app_not_installed：沒有安裝 MarsDawn。只有 open 會回傳這個代碼。
• 4，output_exists：輸出檔已存在，請加上 --force。
• 5，export_failed：匯出本身失敗。
• 64：用法錯誤，例如未知的選項、無效的值、行號超出範圍，或 --line 搭配了多個檔案。這種錯誤一律以文字輸出到 stderr，即使加了 --json 也一樣。

JSON Schema

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

• export.v1.json: export 成功
• open.v2.json: open 成功，marsdawn 0.3.0 以後
• error.v1.json: 兩個指令的失敗結果
• open.v1.json: open 成功，marsdawn 0.2.x，當時 opened 是路徑清單

環境變數

• MARSDAWN_THEME：沒有傳入 --theme 時，export 使用的主題。未知的值會直接改用 dawn，不會報錯。

系統需求

• 這個工具需要 macOS 15 以上。建置需要 Swift 6.2 以上，也就是 Xcode 26 以上。
• MarsDawn app 需要 macOS 26 以上。

安裝

使用 Homebrew。這個 formula 會從原始碼編譯 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 結束。