AI エージェント向け marsdawn

できること

• export：MarsDawn アプリと同じ書き出しエンジンで、1つの Markdown ファイルをページ分割された PDF にレンダリングします。ウインドウは開きません。
• open：1つ以上の Markdown ファイルを MarsDawn アプリで開き、人が確認できるようにします。各ファイルが移動すべき行を指定することもできます。

できないこと

• stdin から Markdown を読み込みません。ファイルパスを渡してください。
• PDF を stdout に書き出しません。PDF は常にファイルとして書き出され、stdout には結果だけが出力されます。
• --force を指定しない限り、既存のファイルを置き換えません。
• --allow-remote-images を指定しない限りウェブから画像を読み込まず、指定した場合も https のみです。
• open は MarsDawn アプリがインストールされていないと動作せず、コード 3 で終了します。export にアプリは不要です。
• MarsDawn 1.0 はまだ open が指定した行にジャンプしません。ファイルは先頭から開きます。
• macOS でのみ動作します。

export

marsdawn export notes.md --json

notes.pdf を notes.md の隣に書き出します。オプション：

• -o, --output <path>：PDF の書き出し先。デフォルトは入力パスの拡張子を .pdf にしたものです。
• --theme <dawn|classic|modern|vivid>：テーマのライトパレット。デフォルトは $MARSDAWN_THEME、それもなければ dawn です。
• --paper <a4|letter>：用紙サイズ。デフォルトは a4 です。
• --allow-remote-images：レンダリング時にウェブから https の画像を読み込みます。
• --force：出力ファイルが存在する場合に置き換えます。
• --json：stdout にテキストではなく1つの 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 図につき1件のメッセージ。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つだけ指定できます。
• 行番号は 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：渡された順に、ファイルごとの1つのオブジェクト。path はファイルの絶対パス、line は行が指定されたときだけ現れます。
• app：それらを開いた MarsDawn アプリのパス。

marsdawn 0.2.x では opened はパス文字列のリストでした。両方を扱う必要がある場合は marsdawn --version を確認してください。

失敗時

--json を指定すると、失敗時は stdout に1つの 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 の指定など。この場合は、--json を指定していても stderr にテキストとして出力されます。

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：export が、--theme が指定されないときに使うテーマ。未知の値はエラーにならず dawn にフォールバックします。

必要環境

• このツールは macOS 15 以降で動作します。Apple シリコンでは、Homebrew がビルド済みのボトルをインストールし、他に何も必要ありません。Intel Mac やソースから自分でビルドする場合は、Swift 6.2 以降が必要で、これは Xcode 26 以降に付属しています。
• MarsDawn アプリには macOS 26 以降が必要です。

インストール

Homebrew を使う場合。Apple シリコンでは、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 で終了します。