Markdansi

https://github.com/steipete/markdansi
Admin
Markdansi is a tiny, dependency-light Markdown to ANSI converter for Node.js terminals with GFM...
Tokens:7,411
Snippets:80
Trust Score:10
License:MIT
Update:6 months ago
Show doc for...
Tokens:
Raw
### Markdansi CLI Usage Examples

Source: https://context7.com/steipete/markdansi/llms.txt

Command-line interface for rendering Markdown. Supports piping input, reading from files, writing to files, and configuring options like width, theme, wrapping, colors, and hyperlinks.

```bash
# Basic usage: pipe markdown through stdin
echo "# Hello **World**" | markdansi
```

```bash
# Render a file
markdansi --in README.md
```

```bash
# Render to a file
markdansi --in README.md --out output.txt
```

```bash
# Custom width and theme
markdansi --width 60 --theme=bright --in docs.md
```

```bash
# Disable wrapping, colors, or links
markdansi --no-wrap --in README.md
markdansi --no-color --in README.md
markdansi --no-links --in README.md
```

--------------------------------

### Install Markdansi with npm, pnpm, or bun

Source: https://github.com/steipete/markdansi/blob/main/README.md

Install the Markdansi package using your preferred Node.js package manager.

```bash
bun add markdansi
```

```bash
pnpm add markdansi
```

```bash
npm install markdansi
```

--------------------------------

### Display CLI Help

Source: https://context7.com/steipete/markdansi/llms.txt

View available command-line options.

```bash
markdansi --help
```

--------------------------------

### Apply Full CLI Configuration

Source: https://context7.com/steipete/markdansi/llms.txt

Apply multiple formatting options simultaneously using command-line flags.

```bash
markdansi --in README.md \
  --width 100 \
  --theme=solarized \
  --list-indent 3 \
  --quote-prefix "│ " \
  --table-border=unicode \
  --table-padding 1 \
  --code-box=true \
  --code-gutter=true
```

--------------------------------

### Configure Code Block Formatting via CLI

Source: https://context7.com/steipete/markdansi/llms.txt

Control code block gutters, boxes, and text wrapping.

```bash
markdansi --code-gutter=true --in code.md
```

```bash
markdansi --code-box=false --code-wrap=false --in code.md
```

--------------------------------

### Configure Table Formatting via CLI

Source: https://context7.com/steipete/markdansi/llms.txt

Adjust table borders, density, padding, and truncation using command-line flags.

```bash
markdansi --table-border=ascii --in table.md
```

```bash
markdansi --table-border=none --table-dense --in table.md
```

```bash
markdansi --table-padding 2 --table-truncate=false --in table.md
```

--------------------------------

### Basic Markdansi Rendering and Customization

Source: https://github.com/steipete/markdansi/blob/main/README.md

Demonstrates basic rendering, disabling wrapping, stripping ANSI codes, and applying custom themes with specific styles for inline and block code.

```javascript
import { render, createRenderer, strip, themes } from 'markdansi';

const ansi = render('# Hello **world**', { width: 60 });

const renderNoWrap = createRenderer({ wrap: false });
const out = renderNoWrap('A very long line...');

// Plain text (no ANSI/OSC)
const plain = strip('link to [x](https://example.com)');

// Custom theme and highlighter hook
const custom = createRenderer({
  theme: {
    ...themes.default,
    code: { color: 'cyan', dim: true }, // fallback used for inline/block
    inlineCode: { color: 'red' },
    blockCode: { color: 'green' },
  },
  highlighter: (code, lang) => code.toUpperCase(),
});
console.log(custom('`inline`

```
block code
```'));
```

--------------------------------

### CLI Usage

Source: https://github.com/steipete/markdansi/blob/main/docs/spec.md

Command line interface usage for rendering Markdown files directly in the terminal.

```APIDOC
## CLI Usage

### Description
Render Markdown files or stdin to the terminal using the markdansi CLI.

### Usage
markdansi [--in FILE] [--out FILE] [--width N] [--no-wrap] [--no-color] [--no-links] [--theme default|dim|bright]

### Parameters
- **--in** (string) - Optional - Input file path. Defaults to stdin.
- **--out** (string) - Optional - Output file path. Defaults to stdout.
- **--width** (number) - Optional - Set the wrapping width.
- **--no-wrap** (boolean) - Optional - Disables hard wrapping.
- **--no-color** (boolean) - Optional - Disables ANSI/OSC styling.
- **--no-links** (boolean) - Optional - Disables OSC-8 hyperlinks.
- **--theme** (string) - Optional - Select a built-in theme.
```

--------------------------------

### Markdansi Render Options

Source: https://context7.com/steipete/markdansi/llms.txt

Configure detailed rendering behavior including text wrapping, colors, hyperlinks, theming, and formatting for lists, blockquotes, tables, and code blocks. A `highlighter` hook is available for custom syntax highlighting.

```typescript
import { render } from 'markdansi';
import type { RenderOptions } from 'markdansi';

const options: RenderOptions = {
  // Text wrapping
  wrap: true,              // Enable hard wrapping (default: true)
  width: 80,               // Wrap width (default: TTY cols or 80)

  // Output control
  color: true,             // Enable ANSI colors (default: TTY detection)
  hyperlinks: true,        // Enable OSC-8 hyperlinks (default: auto-detect)

  // Theming
  theme: 'default',        // 'default' | 'dim' | 'bright' | 'solarized' | 'monochrome' | 'contrast' | Theme object

  // List formatting
  listIndent: 2,           // Spaces per nesting level (default: 2)

  // Blockquote formatting
  quotePrefix: '│ ',       // Prefix for blockquotes (default: '│ ')

  // Table formatting
  tableBorder: 'unicode',  // 'unicode' | 'ascii' | 'none'
  tablePadding: 1,         // Spaces inside cells (default: 1)
  tableDense: false,       // Reduce separator rows (default: false)
  tableTruncate: true,     // Truncate long cells (default: true)
  tableEllipsis: '…',      // Truncation marker (default: '…')

  // Code block formatting
  codeBox: true,           // Draw box around code blocks (default: true)
  codeGutter: false,       // Show line numbers (default: false)
  codeWrap: true,          // Wrap code lines (default: true)

  // Syntax highlighting hook
  highlighter: (code, lang) => {
    // Return ANSI-colored text; must not add/remove newlines
    return code;
  }
};

const markdown = `
# Example

> A blockquote with nested content

- List item 1
  - Nested item
- List item 2

| Header 1 | Header 2 |
|----------|----------|
| Cell 1   | Cell 2   |

\`\`\`typescript
const greeting = 'Hello, World!';
console.log(greeting);
\`\`\`
`;

console.log(render(markdown, options));
```

--------------------------------

### RenderOptions

Source: https://context7.com/steipete/markdansi/llms.txt

Configuration interface for controlling rendering behavior including wrapping, colors, hyperlinks, theming, and formatting of tables, lists, and code blocks.

```APIDOC
## RenderOptions

### Description
Configuration interface for controlling rendering behavior including wrapping, colors, hyperlinks, theming, and formatting of tables, lists, and code blocks.

### Parameters
#### Request Body
- **wrap** (boolean) - Optional - Enable hard wrapping (default: true).
- **width** (number) - Optional - Wrap width (default: TTY cols or 80).
- **color** (boolean) - Optional - Enable ANSI colors.
- **hyperlinks** (boolean) - Optional - Enable OSC-8 hyperlinks.
- **theme** (string|object) - Optional - Theme name or theme object.
- **listIndent** (number) - Optional - Spaces per nesting level.
- **quotePrefix** (string) - Optional - Prefix for blockquotes.
- **tableBorder** (string) - Optional - 'unicode', 'ascii', or 'none'.
- **tablePadding** (number) - Optional - Spaces inside cells.
- **tableDense** (boolean) - Optional - Reduce separator rows.
- **tableTruncate** (boolean) - Optional - Truncate long cells.
- **tableEllipsis** (string) - Optional - Truncation marker.
- **codeBox** (boolean) - Optional - Draw box around code blocks.
- **codeGutter** (boolean) - Optional - Show line numbers.
- **codeWrap** (boolean) - Optional - Wrap code lines.
- **highlighter** (function) - Optional - Syntax highlighting hook.
```

--------------------------------

### createMarkdownStreamer

Source: https://context7.com/steipete/markdansi/llms.txt

Creates a streaming Markdown processor for incremental rendering, ideal for LLM output where content arrives in chunks.

```APIDOC
## createMarkdownStreamer

### Description
Creates a streaming Markdown processor for incremental rendering, ideal for LLM output where content arrives in chunks. The streamer buffers multi-line constructs (fenced code blocks and tables) until complete, ensuring scrollback-safe terminal output.

### Parameters
#### Request Body
- **render** (function) - Required - Function to render markdown string with options.
- **spacing** (string) - Optional - Spacing mode: 'preserve', 'single', or 'tight'.
```

--------------------------------

### Format Lists and Quotes via CLI

Source: https://context7.com/steipete/markdansi/llms.txt

Set indentation for lists and custom prefixes for blockquotes.

```bash
markdansi --list-indent 4 --quote-prefix "> " --in docs.md
```

--------------------------------

### Integrate Shiki Syntax Highlighting

Source: https://context7.com/steipete/markdansi/llms.txt

Use the highlighter hook to convert code blocks into ANSI-colored text using Shiki.

```typescript
import { createRenderer } from 'markdansi';
import { bundledLanguages, bundledThemes, createHighlighter } from 'shiki';

// Create a Shiki highlighter
const shiki = await createHighlighter({
  themes: [bundledThemes['github-dark']],
  langs: [bundledLanguages.typescript, bundledLanguages.javascript, bundledLanguages.python]
});

// Create a markdansi renderer with Shiki highlighting
const render = createRenderer({
  width: 80,
  highlighter: (code, lang) => {
    if (!lang) return code;

    const normalized = lang.toLowerCase();
    const supported = ['ts', 'typescript', 'js', 'javascript', 'py', 'python'];
    if (!supported.includes(normalized)) return code;

    const langMap: Record<string, string> = {
      'ts': 'typescript', 'typescript': 'typescript',
      'js': 'javascript', 'javascript': 'javascript',
      'py': 'python', 'python': 'python'
    };

    const { tokens } = shiki.codeToTokens(code, {
      lang: langMap[normalized] || normalized,
      theme: 'github-dark'
    });

    // Convert Shiki tokens to ANSI escape codes
    return tokens
      .map(line =>
        line
          .map(token => {
            if (!token.color) return token.content;
            const r = parseInt(token.color.slice(1, 3), 16);
            const g = parseInt(token.color.slice(3, 5), 16);
            const b = parseInt(token.color.slice(5, 7), 16);
            return `\u001b[38;2;${r};${g};${b}m${token.content}\u001b[39m`;
          })
          .join('')
      )
      .join('\n');
  }
});

const markdown = `
# Code Examples

\`\`\`typescript
interface User {
  id: number;
  name: string;
}

const getUser = async (id: number): Promise<User> => {
  const response = await fetch(\/api/users/\${id}\`);
  return response.json();
};
\`\`\`

\`\`\`python
def greet(name: str) -> str:
    return f"Hello, {name}!"

print(greet("World"))
\`\`\`
`;

console.log(render(markdown));
```

--------------------------------

### Syntax Highlighting with Shiki and Markdansi

Source: https://github.com/steipete/markdansi/blob/main/README.md

Integrates Shiki for syntax highlighting within Markdansi, rendering TypeScript and Swift code blocks with specific ANSI colors based on Shiki's tokenization.

```javascript
import { bundledLanguages, bundledThemes, createHighlighter } from 'shiki';

const shiki = await createHighlighter({
  themes: [bundledThemes['github-dark']],
  langs: [bundledLanguages.typescript, bundledLanguages.swift],
});

const highlighted = createRenderer({
  highlighter: (code, lang) => {
    if (!lang) return code;
    const normalized = lang.toLowerCase();
    if (!['ts', 'typescript', 'swift'].includes(normalized)) return code;
    const { tokens } = shiki.codeToTokens(code, {
      lang: normalized === 'swift' ? 'swift' : 'ts',
      theme: 'github-dark',
    });
    return tokens
      .map((line) =>
        line
          .map((token) =>
            token.color ? `\u001b[38;2;${parseInt(token.color.slice(1, 3), 16)};${parseInt(
              token.color.slice(3, 5),
              16,
            )};${parseInt(token.color.slice(5, 7), 16)}m${token.content}\u001b[39m` : token.content,
          )
          .join('')
      )
      .join('\n');
  },
});
console.log(highlighted('```ts\nconst x: number = 1\n```\n```swift\nlet x = 1\n```'));
```

--------------------------------

### Library API: createRenderer

Source: https://github.com/steipete/markdansi/blob/main/docs/spec.md

Creates a reusable renderer function with pre-configured options.

```APIDOC
## createRenderer(options)

### Description
Returns a function that accepts a Markdown string and returns the rendered ANSI output using the specified configuration.

### Parameters
#### Request Body
- **options** (RenderOptions) - Optional - Configuration object for the renderer instance.

### Response
- **function** - A function with signature (md: string) => string.
```

--------------------------------

### themes

Source: https://context7.com/steipete/markdansi/llms.txt

A frozen map of built-in themes for styling Markdown output.

```APIDOC
## themes

### Description
A frozen map of built-in themes for styling Markdown output. Available themes: `default`, `dim`, `bright`, `solarized`, `monochrome`, and `contrast`.
```

--------------------------------

### strip(markdown, options)

Source: https://context7.com/steipete/markdansi/llms.txt

Renders Markdown to plain text by removing all ANSI codes and hyperlinks while preserving layout.

```APIDOC
## strip(markdown, options)

### Description
Converts Markdown to plain text, stripping formatting codes while maintaining structure and wrapping.

### Parameters
#### Request Body
- **markdown** (string) - Required - The Markdown content to strip.
- **options** (object) - Optional - Configuration object including width and wrap settings.

### Request Example
strip('# Title', { width: 40, wrap: true });

### Response
#### Success Response (200)
- **plainText** (string) - The resulting plain text string.
```

--------------------------------

### Markdansi CLI Usage

Source: https://github.com/steipete/markdansi/blob/main/README.md

Render Markdown to ANSI from the command line. Supports input/output files, width, wrapping, color, themes, and list/quote styling.

```bash
markdansi [--in FILE] [--out FILE] [--width N] [--no-wrap] [--no-color] [--no-links] [--theme default|dim|bright]
[--list-indent N] [--quote-prefix STR]
```

--------------------------------

### Create Markdown Streamer

Source: https://context7.com/steipete/markdansi/llms.txt

Use `createMarkdownStreamer` for incremental rendering of LLM output. It buffers multi-line constructs to ensure scrollback-safe terminal display. Configure rendering and spacing options.

```typescript
import { createMarkdownStreamer, render } from 'markdansi';

// Create a streamer for LLM-style incremental output
const streamer = createMarkdownStreamer({
  render: (md) => render(md, { width: process.stdout.columns ?? 80 }),
  spacing: 'single' // 'preserve' | 'single' | 'tight'
});

// Simulate streaming chunks (like from an LLM API)
const chunks = [
  '# Hello ',
  'World\n\n',
  'Here is some ',
  '**bold** text.\n\n',
  '```javascript\n',
  'const x = 1;\n',
  'const y = 2;\n',
  '```\n\n',
  '| Col1 | Col2 |\n',
  '|------|------|\n',
  '| A    | B    |\n'
];

for (const chunk of chunks) {
  const output = streamer.push(chunk);
  if (output) process.stdout.write(output);
}

// Flush remaining content at the end
const tail = streamer.finish();
if (tail) process.stdout.write(tail);

// Reset for reuse
streamer.reset();
```

--------------------------------

### Library API: render

Source: https://github.com/steipete/markdansi/blob/main/docs/spec.md

The primary function to convert Markdown strings into ANSI-formatted terminal output.

```APIDOC
## render(markdown, options)

### Description
Converts a Markdown string into an ANSI-formatted string based on the provided options.

### Parameters
#### Request Body
- **markdown** (string) - Required - The Markdown content to render.
- **options** (RenderOptions) - Optional - Configuration object for styling, wrapping, and theme settings.

### Response
- **string** - The resulting ANSI-formatted string.
```

--------------------------------

### Built-in Themes for Markdansi

Source: https://context7.com/steipete/markdansi/llms.txt

Access and utilize predefined themes for styling Markdown output. Themes include `default`, `dim`, `bright`, `solarized`, `monochrome`, and `contrast`. Custom themes can be created by extending built-in ones.

```typescript
import { render, themes, createRenderer } from 'markdansi';

// Use a built-in theme by name
const dimOutput = render('# Hello **World**', { theme: 'dim' });
const brightOutput = render('# Hello **World**', { theme: 'bright' });
const solarizedOutput = render('# Hello **World**', { theme: 'solarized' });
const monochromeOutput = render('# Hello **World**', { theme: 'monochrome' });
const contrastOutput = render('# Hello **World**', { theme: 'contrast' });

// Access theme objects directly for customization
console.log(themes.default);
// { heading: { color: 'yellow', bold: true }, strong: { bold: true }, ... }

// Create a custom theme by extending a built-in
const customTheme = {
  ...themes.default,
  heading: { color: 'magenta', bold: true },
  inlineCode: { color: 'red' },
  blockCode: { color: 'cyan', dim: true }
};

const customRenderer = createRenderer({ theme: customTheme });
console.log(customRenderer('# Custom Theme\n\n`code` and ```\nblock\n```'));
```

--------------------------------

### Import Markdansi Renderer in CommonJS

Source: https://github.com/steipete/markdansi/blob/main/README.md

Use dynamic import for the 'render' function when working in a CommonJS environment or with tools like tsx.

```javascript
const { render } = await import('markdansi');
console.log(render('# hello'));
```

--------------------------------

### Stream Markdown with Markdansi

Source: https://github.com/steipete/markdansi/blob/main/README.md

Process streaming Markdown input, handling multi-line constructs like code blocks and tables correctly before flushing output.

```javascript
import { createMarkdownStreamer, render } from 'markdansi';

const streamer = createMarkdownStreamer({
  render: (md) => render(md, { width: process.stdout.columns ?? 80 }),
  spacing: 'single', // collapse consecutive blank lines
});

process.stdin.setEncoding('utf8');
process.stdin.on('data', (delta) => {
  const chunk = streamer.push(delta);
  if (chunk) process.stdout.write(chunk);
});
process.stdin.on('end', () => {
  const tail = streamer.finish();
  if (tail) process.stdout.write(tail);
});
```

--------------------------------

### Create Reusable Renderers

Source: https://context7.com/steipete/markdansi/llms.txt

Generates a specialized renderer function with pre-configured settings. Useful for maintaining consistent output across multiple calls or applying custom themes and syntax highlighters.

```typescript
import { createRenderer } from 'markdansi';

// Create a renderer with fixed options
const renderNoWrap = createRenderer({ wrap: false, color: true });
const renderDim = createRenderer({ theme: 'dim', width: 60 });
const renderPlain = createRenderer({ color: false, hyperlinks: false });

// Use the pre-configured renderers
const longLine = 'This is a very long line that would normally wrap but with wrap disabled it will extend beyond the terminal width...';
console.log(renderNoWrap(longLine));

const markdown = '# Title\n\nSome **bold** and *italic* text.';
console.log(renderDim(markdown));
console.log(renderPlain(markdown));

// Renderer with custom theme and highlighter
const customRenderer = createRenderer({
  theme: {
    heading: { color: 'magenta', bold: true },
    strong: { bold: true },
    emph: { italic: true },
    inlineCode: { color: 'red' },
    blockCode: { color: 'green' },
    link: { color: 'blue', underline: true },
    quote: { dim: true },
    hr: { dim: true },
    listMarker: { color: 'cyan' },
    tableHeader: { bold: true, color: 'yellow' },
    tableCell: {}
  },
  highlighter: (code, lang) => {
    // Custom syntax highlighting hook
    return code.toUpperCase(); // Example: uppercase all code
  }
});
console.log(customRenderer('`inline`\n\n```js\nconst x = 1;\n```'));
```

--------------------------------

### Strip ANSI Formatting

Source: https://context7.com/steipete/markdansi/llms.txt

Converts Markdown into plain text by removing all ANSI codes and hyperlinks. Preserves the original layout and wrapping structure.

```typescript
import { strip } from 'markdansi';

// Convert markdown to plain text
const markdown = `
# Welcome

Visit [our website](https://example.com) for more info.

- Task 1
- Task 2

\`\`\`javascript
console.log('hello');
\`\`\`
`;

const plainText = strip(markdown);
console.log(plainText);
// Output has no colors, no hyperlinks, but preserves structure

// With custom width for wrapping
const narrowPlain = strip(markdown, { width: 40, wrap: true });
console.log(narrowPlain);
```

--------------------------------

### Render Markdown to ANSI

Source: https://context7.com/steipete/markdansi/llms.txt

Converts Markdown strings into ANSI-formatted terminal output. Supports GFM features like tables and code blocks with configurable styling options.

```typescript
import { render } from 'markdansi';

// Basic rendering with default options
const output = render('# Hello **World**\n\nThis is a *paragraph* with `inline code`.');
console.log(output);

// Rendering with custom options
const customOutput = render(`
# API Documentation

Here's a table of endpoints:

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET    | /users   | List users  |
| POST   | /users   | Create user |

And a code block:

\`\`\`javascript
const api = await fetch('/users');
const users = await api.json();
\`\`\`
`, {
  width: 80,
  wrap: true,
  color: true,
  hyperlinks: true,
  theme: 'default',
  listIndent: 2,
  quotePrefix: '│ ',
  tableBorder: 'unicode',
  tablePadding: 1,
  tableTruncate: true,
  codeBox: true,
  codeGutter: false,
  codeWrap: true
});
console.log(customOutput);
```
Tokens:
Raw