Render Markdown in the Terminal (ANSI) for Node CLIs
The @comark/ansi package renders Markdown to ANSI-styled strings for terminal output.
Installation
pnpm add @comark/ansinpm install @comark/ansiyarn add @comark/ansibun add @comark/ansirenderAnsi()
Parses Markdown and returns an ANSI-styled string in one call.
Usage
import { renderAnsi } from '@comark/ansi'
const output = await renderAnsi(`
# Getting Started
This is a **bold** statement with a [link](https://example.com).
- Item 1
- Item 2
`)
process.stdout.write(output)# Getting Started ← bold + underline
This is a bold statement with a link (https://example.com).
• Item 1
• Item 2Options
| Option | Type | Default | Description |
|---|---|---|---|
plugins | ComarkPlugin[] | [] | Array of plugins |
components | Record<string, fn> | {} | Custom component renderers |
data | Record<string, any> | undefined | Data passed to component renderers |
transformNode | NodeTransform | NodeTransform[] | undefined | Change the tag or props of element nodes right before they render |
colors | boolean | true* | Emit ANSI escape codes |
width | number | 80 | Terminal width for HR and code block headers |
autoClose | boolean | true | Close incomplete Markdown and components before parsing |
autoUnwrap | boolean | true | Remove a single paragraph wrapper inside components |
linkify | boolean | true | Deprecated. Use registerDefaultPlugins: false and register linkify() instead |
registerDefaultPlugins | boolean | true | Register default plugins (linkify, frontmatter, html, alert, task-list, components, attributes) |
unwrap | boolean | string | string[] | false | Remove selected wrapper tags from the parsed document |
*Defaults to false when the NO_COLOR environment variable is set.
renderAnsi() accepts all ParserOptions in addition to the ANSI renderer options above.
plugins
See ComarkPlugin for available plugins.
import { renderAnsi } from '@comark/ansi'
import shiki from '@comark/ansi/plugins/shiki'
const output = await renderAnsi('```typescript\nconsole.log("hello")\n```', {
plugins: [shiki()],
})components
Map component names to async render functions. Each function receives the element as [tag, attrs, ...children] and a context with render to process nested content:
import { renderAnsi } from '@comark/ansi'
const output = await renderAnsi(`
::badge{type="success"}
Build passed
::
`, {
components: {
badge: async ([, attrs, ...children], { render }) => {
return `[${String(attrs.type).toUpperCase()}] ${await render(children)}`
},
},
})
// → [SUCCESS] Build passeddata
Pass external data to every component renderer via the context object:
import { renderAnsi } from '@comark/ansi'
const output = await renderAnsi(`
::status
All systems operational.
::
`, {
data: { env: 'production' },
components: {
status: async ([, , ...children], { render, data }) => {
return `[${data?.env}] ${await render(children)}`
},
},
})
// → [production] All systems operationaltransformNode
Change an element's tag or props right before it renders, using values that are only known at render time. The function receives the node's tag, its resolved props, and the render context. It returns a new tag, new props, or nothing to keep the node as it is. See Transforming nodes before render for the full rules.
import { renderAnsi } from '@comark/ansi'
const output = await renderAnsi('# Release notes', {
transformNode: ({ tag }) => (tag === 'h1' ? { tag: 'h2' } : undefined),
})Comark renders what the function returns as-is. It doesn't strip control characters from it the way it does for the parsed document, so validate anything you build from untrusted data before it reaches the terminal.
Handlers in components receive the transformed node, with the new tag and props.
createAnsiRenderer()
Creates a reusable parse-and-render function. It initializes the parser once and reuses it across calls.
Usage
import { createAnsiRenderer } from '@comark/ansi'
import shiki from '@comark/ansi/plugins/shiki'
const render = createAnsiRenderer({
plugins: [shiki()],
width: 120,
})
const out1 = await render('# Document 1\n\n...')
const out2 = await render('# Document 2\n\n...')Options
Same as renderAnsi().
printAnsi()
Parses and prints Markdown directly to stdout in one call.
printAnsi() replaces writeAnsi(), which is deprecated and will be removed in the next major version.Usage
import { printAnsi } from '@comark/ansi'
await printAnsi(`
# Hello World
This is **bold**, _italic_, and \`inline code\`.
> [!NOTE]
> @comark/ansi renders GitHub-style alerts with color.
`)Options
Pass options to configure the parser, renderer, or output destination using writer:
import { printAnsi } from '@comark/ansi'
import math, { Math } from '@comark/ansi/plugins/math'
await printAnsi('Inline $E = mc^2$', {
plugins: [math()],
components: { Math },
width: 100,
writer: (s) => process.stderr.write(s),
})They are the same options as renderAnsi() plus the writer?: (string: string) => void option.
createAnsiPrinter()
Creates a reusable printer with pre-configured options. It initializes the parser once and reuses it across calls.
createAnsiPrinter() replaces createAnsiWriter(), which is deprecated and will be removed in the next major version.Usage
import { createAnsiPrinter } from '@comark/ansi'
import math, { Math } from '@comark/ansi/plugins/math'
import shiki from '@comark/ansi/plugins/shiki'
const print = createAnsiPrinter({
plugins: [math(), shiki()],
components: { Math },
width: 120,
})
await print('# Document 1\n\n...')
await print('# Document 2\n\n...')Options
Same as printAnsi().
renderAnsiFromDocument()
Renders a pre-parsed MarkdownDocument to an ANSI string, with no parsing step. Use this when you already have a parsed document.
Integration
import { parseMarkdown } from 'comark'
import { renderAnsiFromDocument } from '@comark/ansi'
const document = await parseMarkdown(`
# Getting Started
This is a **bold** statement with a [link](https://example.com).
- Item 1
- Item 2
`)
const output = await renderAnsiFromDocument(document)
process.stdout.write(output)Options
| Option | Type | Default | Description |
|---|---|---|---|
components | Record<string, fn> | {} | Custom component renderers |
data | Record<string, any> | undefined | Data passed to component renderers |
transformNode | NodeTransform | NodeTransform[] | undefined | Change the tag or props of element nodes right before they render |
colors | boolean | true* | Emit ANSI escape codes |
width | number | 80 | Terminal width for HR and code block headers |
*Defaults to false when the NO_COLOR environment variable is set.
Overriding terminal output
Pass native Markdown tag names as keys in components to override how standard elements render in the terminal:
import { createAnsiRenderer } from '@comark/ansi'
const renderAnsi = createAnsiRenderer({
components: {
h1: async ([, , ...children], { render }) => {
return `\x1b[1;4;35m★ ${await render(children)}\x1b[0m\n`
},
a: async ([, attrs, ...children], { render }) => {
const label = await render(children)
return `\x1b[36m${label}\x1b[0m (\x1b[2m${attrs.href}\x1b[0m)`
},
},
})Syntax support
Headings
Comark styles headings by level, using bold and underline for h1 and distinct colors down to h6.
GitHub alerts
Blockquotes with [!TYPE] markers render as colored alerts matching GitHub's style:
> [!NOTE]
> Informational message.
> [!TIP]
> Helpful suggestion.
> [!IMPORTANT]
> Key information.
> [!WARNING]
> Potential risk.
> [!CAUTION]
> Danger ahead.Each type has its own color: NOTE → blue, TIP → green, IMPORTANT → magenta, WARNING → yellow, CAUTION → red.
Code blocks
Code blocks show the language and filename in a header line. When the shiki plugin is used, tokens are rendered with true-color ANSI (\x1b[38;2;R;G;Bm) derived from Shiki's dark theme:
import { createAnsiPrinter } from '@comark/ansi'
import shiki from '@comark/ansi/plugins/shiki'
const printAnsi = createAnsiPrinter({ plugins: [shiki()] })
await printAnsi('```typescript [app.ts]\nconsole.log("hello")\n```')
// typescript app.ts
// console.log("hello") ← syntax highlightedMath
Math expressions from the math plugin render as colored LaTeX source, with inline math in yellow and block math in magenta:
import { createAnsiPrinter } from '@comark/ansi'
import math, { Math } from '@comark/ansi/plugins/math'
const printAnsi = createAnsiPrinter({ plugins: [math()], components: { Math } })
await printAnsi('Inline $E = mc^2$ and block:\n\n$$\n\\frac{a}{b}\n$$')Tables
Tables render with box-drawing characters:
┌─────────────┬─────────┐
│ Feature │ Status │
├─────────────┼─────────┤
│ Headings │ ✅ │
│ Code blocks │ ✅ │
└─────────────┴─────────┘TypeScript support
import type { AnsiRendererOptions } from '@comark/ansi'
import { createAnsiRenderer } from '@comark/ansi'
import type { NodeHandler } from 'comark'
const components: Record<string, NodeHandler> = {
badge: async ([, attrs, ...children], { render }) => {
return `[${String(attrs.type).toUpperCase()}] ${await render(children)}`
},
}
const options: AnsiRendererOptions = { colors: true, width: 100, components }
const renderAnsi = createAnsiRenderer(options)