Automation and JSON Events

Automation and JSON Events

Use --json when another program needs stable, machine-readable progress. Leafmark emits one JSON object per line with schemaVersion: 1 and a type field.

pnpx @skxv/leafmark ./report --json

Build events

build-started

{
  "schemaVersion": 1,
  "type": "build-started",
  "bundle": null,
  "input": "/path/report",
  "output": "/path/dist",
  "chapters": ["introduction.md"],
  "words": 420,
  "characters": 2871
}

artifact

Emitted for each completed output:

{
  "schemaVersion": 1,
  "type": "artifact",
  "format": "pdf",
  "path": "/path/dist/report.pdf"
}

Possible artifact formats are pdf, docx, and html.

complete

{
  "schemaVersion": 1,
  "type": "complete",
  "command": "build",
  "success": true
}

Status event

pnpx @skxv/leafmark status ./report --json

Emits status with bundle, input, chapters, words, charactersWithSpaces, and charactersWithoutSpaces.

Diagnostic events

pnpx @skxv/leafmark doctor --json

Emits one diagnostic per core tool with name, command, and available, followed by complete.

Theme events

pnpx @skxv/leafmark theme list --json

Emits one theme event with name, description, and builtin: true, followed by complete.

CI example

name: Build document
on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: sudo apt-get update
      - run: sudo apt-get install -y pandoc texlive-xetex poppler-utils
      - run: npx --yes @skxv/leafmark --skip-tools-check
      - uses: actions/upload-artifact@v4
        with:
          name: document
          path: dist/*.pdf

Pin the npm package version in production workflows for reproducibility. Add a Chromium package when documents contain HTML blocks rendered into PDF or DOCX.

Integration guidance

• Parse stdout one line at a time.
• Branch on schemaVersion before assuming event fields.
• Treat nonzero process exit as failure even if earlier artifacts were emitted.
• Paths are absolute in events.
• Avoid parsing the human-readable mode; it is intended for terminal users.