MarsDawn

marsdawn para agentes

Una referencia para agentes de IA y scripts que llaman a la herramienta de línea de comandos marsdawn. Cada ejemplo de esta página se ejecutó con la herramienta compilada desde el código fuente actual.

Para convertir un archivo Markdown en PDF, ejecuta marsdawn export notes.md --json y lee un objeto JSON de stdout. Los diagramas Mermaid y el código resaltado se renderizan igual que en la app MarsDawn. export no necesita la app; open, sí.

Qué hace

Qué no hace

export

marsdawn export notes.md --json

Escribe notes.pdf junto a notes.md. Opciones:

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

Éxito, código de salida 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

Éxito, código de salida 0:

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

Con una carpeta (marsdawn 0.5.1 y posterior), código de salida 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 imprimía opened como una lista de rutas en texto. Revisa marsdawn --version si necesitas manejar ambos casos.

Abrir archivos mientras Claude Code los edita

Un hook de Claude Code opcional: después de que Claude escribe o edita un archivo Markdown, lo abre en MarsDawn en segundo plano, una vez por archivo y por sesión. Está desactivado hasta que lo agregas, proyecto por proyecto, porque una ventana que no pediste se lleva tu atención. Ejecuta un comando de shell y no gasta tokens del modelo.

Necesita marsdawn 0.5.1 o posterior, por --background, y la app MarsDawn.

Guarda esto como .claude/hooks/marsdawn-open.sh en tu proyecto y hazlo ejecutable con 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

Luego agrega el hook a .claude/settings.json en el proyecto, o a .claude/settings.local.json para que sea solo tuyo:

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

Errores

Con --json, un error imprime un objeto JSON en stdout y termina con su código:

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

Esquemas JSON

JSON Schema (draft 2020-12) para cada resultado de --json:

Variables de entorno

Requisitos

Instalación

Con Homebrew. En chips de Apple instala un bottle precompilado en segundos, sin necesidad de Xcode. En una Mac con Intel compila marsdawn desde el código fuente, lo que tarda unos minutos y requiere Xcode 26 o posterior.

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

O compílala desde el código fuente. La primera compilación descarga las dependencias y compila, lo que también tarda unos minutos.

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 imprime el número de versión, como 0.3.0, y termina con el código 0.

Siguiente