给 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 以上。在 Apple 芯片的 Mac 上，Homebrew 会安装预先构建好的版本，不需要其他东西。自己构建时（在 Intel Mac 上，或从源代码构建），需要 Swift 6.2 以上，也就是 Xcode 26 以上。
• MarsDawn app 需要 macOS 26 以上。

安装

使用 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 结束。