@gum-jsx/mark

Markdown-to-terminal rendering for Gum. It renders ANSI-styled text with fenced gum code blocks, local PNG/JSX images, and TeX math displayed through the kitty graphics protocol.

See the Gum project for getting started and the package overview.

Command line

npm install -g @gum-jsx/mark

gum-mark notes.md -t light -H 100
gum-mark notes.md -p
printf 'Hello $x^2$\n' | gum-mark

The bundled gum-mark executable (also available as gumd) runs under Node.js 24+ or Bun 1.4.2+. It includes the Markdown parser, Gum renderer, fonts, and PNG WebAssembly. The package retains its source library exports and their dependencies. Omit the file or use - to read stdin. The terminal must support the kitty graphics protocol; pager mode also needs Unicode placeholder support and less -R.

Code block options width=, height=, and theme= override the command-wide settings. Image alt text accepts the same options, such as ![height=300](figure.png).

# A short note

Inline math: $e^{i\pi}+1=0$.

```gum width=320 theme=light
<Frame padding={em(1)}>
  <Text>Hello, Gum</Text>
</Frame>
```

Local image paths resolve from the process's working directory. Gum fences and JSX images execute JavaScript through the evaluator; render trusted documents.

Library usage

The source library API requires Bun or a compatible TypeScript bundler.

import { displayMarkdown } from '@gum-jsx/mark'

const markdown = '# Hello\n\nInline math: $x^2$'
process.stdout.write(displayMarkdown(markdown, { theme: 'light', width: 800 }))

displayMarkdown(content, options?) returns a string containing ANSI text and kitty image sequences. Gum figures and math use @gum-jsx/png and tiny-skia WebAssembly without native addons or install scripts. Live text, emoji without outlines, and external SVG images are unsupported. Use PNG or JSX images. Local PNGs are sent directly to the terminal.

| Option | Meaning | | --- | --- | | theme | Figure and math palette: light or dark. | | width | Maximum figure/image width in pixels. | | imageHeight | Maximum figure/image height; default 500 pixels. | | height | Display-math render height. | | inlineHeight | Inline-math render height. | | scope | Additional bindings for evaluated Gum source. | | cell | Terminal cell size in pixels, for image placement. | | virtual | Image transmission callback and cell geometry for placeholder output. |

queryCellSize() and readStdin() are also exported. The CLI handles terminal queries and pager setup; run gum-mark --help for its options and defaults.

Development

From this package directory:

bun run build
bun run test
bun run typecheck

build writes the Node-compatible CLI and bundled assets/licenses to dist/npm/. npm pack and npm publish invoke it through prepack.

Tests exercise the source CLI and the packed executable under Node and Bun.