<img src="https://github.com/comarkdown/comark/blob/main/assets/banner.jpg" width="100%" alt="Comark banner" />

# @comark/ansi

[![npm version](https://img.shields.io/npm/v/@comark/ansi?color=black)](https://npmx.dev/@comark/ansi)
[![npm downloads](https://img.shields.io/npm/dm/@comark/ansi?color=black)](https://npm.chart.dev/@comark/ansi)
[![CI](https://img.shields.io/github/actions/workflow/status/comarkdown/comark/ci.yml?branch=main&color=black)](https://github.com/comarkdown/comark/actions/workflows/ci.yml)
[![Documentation](https://img.shields.io/badge/Documentation-black?logo=readme&logoColor=white)](https://comark.dev/rendering/ansi)
[![license](https://img.shields.io/github/license/comarkdown/comark?color=black)](https://github.com/comarkdown/comark/blob/main/LICENSE)

ANSI terminal renderer for [Comark](https://comark.dev). Render markdown as styled terminal output for CLIs, scripts, and developer tooling.

## Features

- 🎨 ANSI-styled output for the terminal
- 🌈 Respects `NO_COLOR` automatically
- 📐 Configurable terminal width for HR and code blocks
- 🎯 Map any Comark tag to a custom render function
- 🔌 Plugin ecosystem (math, mermaid, highlight, binding…)
- 🎯 Full TypeScript support

## Installation

```bash
npm install @comark/ansi
# or
pnpm add @comark/ansi
```

## Usage

```ts
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)
```

### Options

```ts
await renderAnsi(content, {
  colors: true,   // emit ANSI escape codes (defaults to true, false when NO_COLOR is set)
  width: 80,      // terminal width for HR and code block headers
  plugins: [],
  components: {},
})
```

### Syntax highlighting

```ts
import { renderAnsi } from '@comark/ansi'
import shiki from '@comark/ansi/plugins/shiki'

const output = await renderAnsi('```ts\nconsole.log("hi")\n```', {
  plugins: [shiki()],
})
```

## API

- `renderAnsi(markdown, options?)` parses and renders Markdown to an ANSI string.
- `createAnsiRenderer(options?)` creates a reusable parse-and-render function.
- `renderAnsiFromDocument(document, options?)` renders a pre-parsed `MarkdownDocument`.
- `printAnsi(markdown, options?)` parses and writes Markdown to `process.stdout` or a custom `writer`. (`writeAnsi` is a deprecated alias.)
- `createAnsiPrinter(options?)` creates a reusable printer. (`createAnsiWriter` is a deprecated alias.)

```ts
import { createAnsiPrinter } from '@comark/ansi'

const printAnsi = createAnsiPrinter({
  colors: false,
  writer: (output) => process.stderr.write(output),
})

await printAnsi('# Build complete')
```

## Documentation

Full guide and API reference at [comark.dev/rendering/ansi](https://comark.dev/rendering/ansi).

## License

Made with ❤️

Published under [MIT License](https://github.com/comarkdown/comark/blob/main/LICENSE).