Markdown Table

Generate copy-ready Markdown tables without juggling column widths or accidentally breaking ANSI-colored strings.

Summary

The MarkdownTable battery turns rows of text into perfectly aligned Markdown tables. It returns a ready-to-print string you can drop into terminal logs, CI updates, or support runbooks without hand-tuning spacing.

Why Use This Battery?

1. Way easier to scan than dumping raw JSON or console logs into an update.
2. ANSI-supported output for terminals, and clean, copy‑ready Markdown for docs.
3. Keeps diffs tidy in Git, so reviewers spot row-level changes fast.

Capabilities

• Accounts for ANSI colors and escapes special characters so tables align correctly and render cleanly.
• Enforces header and row parity, so to stop malformed tables from being generated.
• Built-in minimum column sizing and optional padded separators create copy-paste-ready tables.
• Chained row insertion lets automation pipelines stream data directly into reports with ease.

Usage

Good to Know

Examples use TypeScript, but the API is identical in JavaScript (ESM-only).

Basic table

import { MarkdownTable } from '@cbnventures/nova/toolkit';

const table = new MarkdownTable(
  [
    'Tool',
    'Version',
  ],
);

table
  .addRow(['Nova CLI', '1.2.0'])
  .addRow(['Node.js', process.version]);

process.stdout.write(`${table.render()}\n`);

ANSI-aware

import { MarkdownTable } from '@cbnventures/nova/toolkit';
import chalk from 'chalk';

const table = new MarkdownTable(
  [
    'Check',
    'Result',
  ],
  {
    minimumColumnWidth: 6,
    padDelimiterRow: true,
  },
);

table
  .addRow([chalk.green('Unit tests'), chalk.green('PASS')])
  .addRow([chalk.yellow('Docs'), chalk.yellow('WARN')]);

process.stdout.write(`${table.render()}\n`);

From objects + streaming

import { MarkdownTable } from '@cbnventures/nova/toolkit';

const tasks = [
  {
    name: 'Build',
    status: 'Complete',
    elapsedMs: 3200,
  },
  {
    name: 'Test',
    status: 'Pass',
    elapsedMs: 18200,
  },
  {
    name: 'Deploy',
    status: 'Pending',
    elapsedMs: 0,
  },
];

const table = new MarkdownTable(
  [
    'Task',
    'Status',
    'Duration',
  ],
);

for (const task of tasks) {
  table.addRow([task.name, task.status, `${task.elapsedMs} ms`]);

  // Optional: stream the latest snapshot to the log.
  // process.stdout.write(`${table.render()}\n`);
}

process.stdout.write(`${table.render()}\n`);

Output Examples

Basic table

ANSI-aware

From objects + streaming

Customize

Tune the runtime behavior with the environment variables and options below.

Options

Pass these options into the MarkdownTable constructor to control column widths and delimiter formatting so the output works in both terminals and docs.

Option	Type	Default	Description
minimumColumnWidth	number	3	Smallest visible width per column; anything below 3 is promoted to 3.
padDelimiterRow	boolean	false	When true, outputs GitHub-style delimiter rows with surrounding spaces (e.g., | --- |).

Troubleshooting

• "headers" must be a non-empty array. — Ensure you pass at least one header string when constructing the table.
• Length of "rows" must equal length of "headers". — Each row array must align with the number of headers; pad missing cells before calling addRow.
• Unexpected spacing? — Increase minimumColumnWidth when cells contain long strings or disable delimiter padding by leaving padDelimiterRow at its default.