markstream-cli

Stream-render Markdown in a real terminal (with optional async code highlighting).

Install

pnpm add markstream-cli
# or: npm i markstream-cli
# or: yarn add markstream-cli

CLI

cat README.md | markstream --theme nord --final-only
markstream ./README.md --no-color

markstream --help

--theme <theme> enables Shiki ANSI highlighting, even when stdout is piped. Use --no-color to disable ANSI styling and syntax highlighting.

Usage

One-shot streaming to terminal:

import { createShikiHighlightCode, streamMarkdownToTerminal } from 'markstream-cli'

async function* chunks() {
  yield '# Hello\n\n'
  yield '```ts\nconst x = 1\n'
  yield '```\n'
}

await streamMarkdownToTerminal(chunks(), {
  terminal: { clear: true },
  // Optional debug instrumentation:
  // debug: { patches: true },
  render: {
    highlightCode: createShikiHighlightCode({ theme: 'nord' as any }),
  },
})

Demos (repo)

These require a real TTY (run in an interactive terminal; not captured output).

• pnpm run demo:stream: character-by-character markdown streaming + code fence completion
• pnpm run demo:highlight-md: stream a larger markdown fixture + async code highlighting
• pnpm test: run unit tests

Styling notes (terminal)

**strong** is rendered using ANSI "bold" (SGR 1). Whether it looks bold depends on your terminal + font/theme:

• Some terminals/fonts show little/no difference for bold text (it may map to a brighter color instead).
• VS Code integrated terminal can look subtle depending on your font and theme.

If you need strong to be visually obvious everywhere, override the render theme:

await streamMarkdownToTerminal(chunks(), {
  render: {
    // Make strong more visible across terminals:
    theme: { strong: { bold: true, underline: true } },
  },
})

Advanced: low-level renderer

If you want to manage terminal I/O yourself (or integrate with another terminal abstraction), use createMarkdownStreamRenderer():

import { createMarkdownStreamRenderer } from 'markstream-cli'

const r = createMarkdownStreamRenderer({
  strategy: 'smart', // append when possible
  render: { color: true },
})

process.stdout.write(r.push('# Title\n\nHello **world**.\n'))
process.stdout.write(r.push('```ts\nconst x = 1\n'))
process.stdout.write(r.push('```'))
for (const patch of await r.flush())
  process.stdout.write(patch)

Security

Markdown text is sanitized by default before it is written to the terminal, so raw ESC/BEL/C1 control sequences from untrusted input are rendered as visible symbols instead of being executed by the terminal. Custom highlightCode functions receive sanitized code by default unless render.allowControlSequences is enabled.

To allow raw control sequences from Markdown code blocks to reach Shiki output, enable both render.allowControlSequences: true and createShikiHighlightCode({ theme, allowControlSequences: true }). The render option controls whether raw Markdown input is sanitized before it reaches the highlighter; the Shiki option controls whether Shiki token content is sanitized before ANSI styling is applied.

The string returned from a custom highlighter is treated as trusted terminal output, because highlighters are expected to emit ANSI styling; use trusted highlighters only.

Troubleshooting

• Nothing updates / looks wrong when piping: streaming requires a TTY. For programmatic usage set terminal.stream.isTTY = true only if your target really is a terminal.
• Flicker during rewrites: prefer streamMarkdownToTerminal() (it uses synchronized updates and streaming-friendly patching), or set strategy: 'smart' unless you need full redraw behavior.

:coffee:

buy me a cup of coffee

License

MIT

Sponsors