Markdown Table

https://github.com/wooorm/markdown-table
Admin
A simple package that generates GitHub Flavored Markdown (GFM) tables from provided data, with...
Tokens:10,972
Snippets:83
Trust Score:9.8
License:MIT
Update:4 days ago
Show doc for...
Tokens:
Raw
### options.delimiterStart: false example

Source: https://github.com/wooorm/markdown-table/blob/main/readme.md

Example of a markdown table generated with starting delimiters disabled.

```markdown
Alpha | B     |
----- | -----
C     | Delta
```

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

### Install via npm

Source: https://github.com/wooorm/markdown-table/blob/main/readme.md

Install the package using npm for Node.js environments.

```sh
npm install markdown-table
```

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

### options.padding: false example

Source: https://github.com/wooorm/markdown-table/blob/main/readme.md

Example of a markdown table generated with padding disabled.

```markdown
|Alpha|B    |
|-----|-----|
|C    |Delta|
```

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

### options.padding: true example

Source: https://github.com/wooorm/markdown-table/blob/main/readme.md

Example of a markdown table generated with padding enabled (default).

```markdown
| Alpha | B     |
| ----- | ----- |
| C     | Delta |
```

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

### Install via Browser

Source: https://github.com/wooorm/markdown-table/blob/main/readme.md

Import the package in a browser environment using a module script.

```html
<script type="module">
  import {markdownTable} from 'https://esm.sh/markdown-table@3?bundle'
</script>
```

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

### Install via Deno

Source: https://github.com/wooorm/markdown-table/blob/main/readme.md

Import the package in Deno using esm.sh.

```js
import {markdownTable} from 'https://esm.sh/markdown-table@3'
```

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

### options.alignDelimiters: false example

Source: https://github.com/wooorm/markdown-table/blob/main/readme.md

Example of a markdown table generated with staggered delimiters.

```markdown
| Alpha | B |
| - | - |
| C | Delta |
```

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

### options.delimiterEnd: false example

Source: https://github.com/wooorm/markdown-table/blob/main/readme.md

Example of a markdown table generated with ending delimiters disabled.

```markdown
| Alpha | B
| ----- | -----
| C     | Delta
```

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

### options.stringLength: custom implementation

Source: https://github.com/wooorm/markdown-table/blob/main/readme.md

Example using the string-width package to correctly align full-width characters and emojis.

```js
import stringWidth from 'string-width'

markdownTable(
  [
    ['Alpha', 'Bravo'],
    ['中文', 'Charlie'],
    ['👩‍❤️‍👩', 'Delta']
  ],
  {stringLength: stringWidth}
)
```

```markdown
| Alpha | Bravo   |
| ----- | ------- |
| 中文  | Charlie |
| 👩‍❤️‍👩    | Delta   |
```

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

### Example output for typical input

Source: https://github.com/wooorm/markdown-table/blob/main/_autodocs/api-reference/markdown-table.md

A representation of the markdown output generated by the library for a standard table input.

```markdown
| Branch  | Commit           |
| ------- | ---------------- |
| main    | 0123456789abcdef |
| staging | fedcba9876543210 |
```

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

### Basic usage of markdownTable

Source: https://github.com/wooorm/markdown-table/blob/main/_autodocs/api-reference/markdown-table.md

A basic example showing how to import and use markdownTable to convert a 2D array into a markdown table string.

```js
import {markdownTable} from 'markdown-table'

const table = markdownTable([
  ['Branch', 'Commit'],
  ['main', '0123456789abcdef'],
  ['staging', 'fedcba9876543210']
])

console.log(table)
// | Branch  | Commit           |
// | ------- | ---------------- |
// | main    | 0123456789abcdef |
// | staging | fedcba9876543210 |
```

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

### options.stringLength: default behavior

Source: https://github.com/wooorm/markdown-table/blob/main/readme.md

Example showing how default string length calculation handles full-width characters and emojis.

```js
markdownTable([
  ['Alpha', 'Bravo'],
  ['中文', 'Charlie'],
  ['👩‍❤️‍👩', 'Delta']
])
```

```markdown
| Alpha | Bravo |
| - | - |
| 中文 | Charlie |
| 👩‍❤️‍👩 | Delta |
```

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

### Control edge delimiters with delimiterStart and delimiterEnd

Source: https://github.com/wooorm/markdown-table/blob/main/_autodocs/configuration.md

Demonstrates how to remove the start or end delimiters from the generated table.

```js
markdownTable(
  [
    ['Branch', 'Commit'],
    ['main', '0123456789abcdef']
  ],
  {delimiterStart: false}
)
// Branch | Commit           |
// ------ | ---------------- |
// main   | 0123456789abcdef |
```

```js
markdownTable(
  [
    ['Branch', 'Commit'],
    ['main', '0123456789abcdef']
  ],
  {delimiterEnd: false}
)
// | Branch | Commit
// | ------ | ----------------
// | main   | 0123456789abcdef
```

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

### Generate a default table

Source: https://github.com/wooorm/markdown-table/blob/main/readme.md

Create a basic GFM table with default left alignment.

```js
import {markdownTable} from 'markdown-table'

markdownTable([
  ['Branch', 'Commit'],
  ['main', '0123456789abcdef'],
  ['staging', 'fedcba9876543210']
])
```

```markdown
| Branch  | Commit           |
| ------- | ---------------- |
| main    | 0123456789abcdef |
| staging | fedcba9876543210 |
```

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

### Advanced usage with alignment and custom string length

Source: https://github.com/wooorm/markdown-table/blob/main/_autodocs/api-reference/markdown-table.md

Demonstrates using column alignment and a custom stringLength function to handle visible width for ANSI-colored text.

```js
import chalk from 'chalk'
import {markdownTable} from 'markdown-table'

// Length function measuring the *visible* width of a cell.
function stringLength(value) {
  return stripAnsi(value).length // e.g. from the 'strip-ansi' package
}

const table = markdownTable(
  [
    ['A', 'B', 'C'],
    [chalk.red('Red'), chalk.green('Green'), chalk.blue('Blue')],
    ['bar', '45', 'lmno']
  ],
  {align: ['', 'c', 'r'], stringLength}
)

console.log(table)
// | A   |   B   |    C |
// | --- | :---: | ---: |
// | Red | Green | Blue |
// | bar |  45   | lmno |
```

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

### markdownTable(table[, options])

Source: https://github.com/wooorm/markdown-table/blob/main/readme.md

Generates a markdown table from a matrix of strings. Accepts a table (array of arrays of strings) and optional configuration options to control alignment, padding, delimiters, and string length measurement.

```APIDOC
## markdownTable(table[, options])

### Description
Generates a markdown table from table data (matrix of strings).

### Parameters
#### table
- **table** (Array<Array<string>>) - Required - The table data as a matrix of strings.

#### options (optional)
- **align** (string | Array<string>) - Optional - One style for all columns, or styles for their respective columns. Each style is either 'l' (left), 'r' (right), or 'c' (center). Other values are treated as '', which doesn't place the colon in the alignment row but does align left. Only the lowercased first character is used, so 'Right' is fine.
- **padding** (boolean) - Optional, default: true - Whether to add a space of padding between delimiters and cells.
- **delimiterStart** (boolean) - Optional, default: true - Whether to begin each row with the delimiter.
- **delimiterEnd** (boolean) - Optional, default: true - Whether to end each row with the delimiter.
- **alignDelimiters** (boolean) - Optional, default: true - Whether to align the delimiters.
- **stringLength** (Function) - Optional, default: s => s.length - Function to detect the length of table cell content. This is used when aligning the delimiters between table cells.

### Return Value
Returns a string containing the generated markdown table.

### Examples
#### Basic usage
```js
markdownTable([
  ['Alpha', 'Bravo'],
  ['中文', 'Charlie'],
  ['👩‍❤️‍👩', 'Delta']
])
```

Yields:
```markdown
| Alpha | Bravo |
| - | - |
| 中文 | Charlie |
| 👩‍❤️‍👩 | Delta |
```

#### With stringLength option
```js
import stringWidth from 'string-width'

markdownTable(
  [
    ['Alpha', 'Bravo'],
    ['中文', 'Charlie'],
    ['👩‍❤️‍👩', 'Delta']
  ],
  {stringLength: stringWidth}
)
```

Yields:
```markdown
| Alpha | Bravo   |
| ----- | ------- |
| 中文  | Charlie |
| 👩‍❤️‍👩    | Delta   |
```
```

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

### markdownTable(table[, options])

Source: https://github.com/wooorm/markdown-table/blob/main/readme.md

Generates a GitHub flavored markdown table from the provided data. The table parameter is an array of rows, each row being an array of cell strings. The optional options object can include an align property to specify column alignment.

```APIDOC
## markdownTable(table[, options])

### Description
Generates a GitHub flavored markdown table from the provided data. The table parameter is an array of rows, each row being an array of cell strings. The optional options object can include an align property to specify column alignment.

### Parameters
#### table (Array<Array<string>>) - Required
- An array of rows, each row is an array of cell strings.

#### options (Object) - Optional
- **align** (Array<string>) - Optional - An array of alignment values ('l', 'c', 'r') for each column. Defaults to left alignment.

### Return Value
- **string** - The generated markdown table as a string.

### Example
```js
import {markdownTable} from 'markdown-table'

markdownTable([
  ['Branch', 'Commit'],
  ['main', '0123456789abcdef'],
  ['staging', 'fedcba9876543210']
])
```

Yields:

```markdown
| Branch  | Commit           |
| ------- | ---------------- |
| main    | 0123456789abcdef |
| staging | fedcba9876543210 |
```

With align:

```js
markdownTable(
  [
    ['Beep', 'No.', 'Boop'],
    ['beep', '1024', 'xyz'],
    ['boop', '3388450', 'tuv'],
    ['foo', '10106', 'qrstuv'],
    ['bar', '45', 'lmno']
  ],
  {align: ['l', 'c', 'r']}
)
```

Yields:

```markdown
| Beep |   No.   |   Boop |
| :--- | :-----: | -----: |
| beep |   1024  |    xyz |
| boop | 3388450 |    tuv |
| foo  |  10106  | qrstuv |
| bar  |    45   |   lmno |
```
```

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

### Generate a table with alignment

Source: https://github.com/wooorm/markdown-table/blob/main/readme.md

Create a GFM table with custom column alignment using the align option.

```js
markdownTable(
  [
    ['Beep', 'No.', 'Boop'],
    ['beep', '1024', 'xyz'],
    ['boop', '3388450', 'tuv'],
    ['foo', '10106', 'qrstuv'],
    ['bar', '45', 'lmno']
  ],
  {align: ['l', 'c', 'r']}
)
```

```markdown
| Beep |   No.   |   Boop |
| :--- | :-----: | -----: |
| beep |   1024  |    xyz |
| boop | 3388450 |    tuv |
| foo  |  10106  | qrstuv |
| bar  |    45   |   lmno |
```

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

### Default alignment with markdownTable

Source: https://github.com/wooorm/markdown-table/blob/main/_autodocs/configuration.md

Demonstrates the default left-aligned behavior when no alignment options are provided.

```js
import {markdownTable} from 'markdown-table'

markdownTable([
  ['Alpha', 'B'],
  ['C', 'Delta']
])
// | Alpha | B     |
// | ----- | ----- |
// | C     | Delta |
```

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

### Usage with staggered delimiters and missing cells

Source: https://github.com/wooorm/markdown-table/blob/main/_autodocs/api-reference/markdown-table.md

Shows how to disable delimiter alignment and handle rows with varying lengths or empty cells.

```js
import {markdownTable} from 'markdown-table'

const table = markdownTable(
  [
    ['A', 'B', 'C'],
    ['a', 'b', 'c'],
    ['a', 'b'], // missing third cell
    []          // empty row
  ],
  {alignDelimiters: false, align: ['l', 'c', 'r']}
)

console.log(table)
// | A | B | C |
// | :- | :-: | -: |
// | a | b | c |
// | a | b | |
// | | | |
```

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

### markdownTable()

Source: https://github.com/wooorm/markdown-table/blob/main/_autodocs/configuration.md

The markdownTable function generates a markdown table from an array of rows. It accepts an options object to customize alignment, delimiters, padding, and string width calculation.

```APIDOC
## markdownTable(rows[, options])

### Description
Generates a markdown table from a matrix of strings. The options object allows customization of column alignment, delimiter padding, cell padding, and string width measurement.

### Method
Function call

### Endpoint
markdownTable(rows, options)

### Parameters
#### rows (Array<Array<string>>) - Required
- The data rows of the table. Each row is an array of strings.

#### options (Object) - Optional
- **align** (Array<string>) - Optional - Per-column alignment. Values: 'l' (left), 'c' (center), 'r' (right). Multi-character tokens are accepted; only the lowercased first character matters. Default: left-aligned.
- **alignDelimiters** (boolean) - Optional - When false, cell sizes are computed but not used for padding; the alignment row uses a hyphen run of exactly 1 (plus colons), and empty cells are followed by a single space. Default: true.
- **delimiterStart** (boolean) - Optional - When false, the leading pipe is omitted. Default: true.
- **delimiterEnd** (boolean) - Optional - When false, the trailing pipe is omitted. Default: true.
- **padding** (boolean) - Optional - When false, no spaces are added around cell content. Default: true.
- **stringLength** (function) - Optional - A function that receives each serialized cell as a string and returns a number representing its visible width. Used to fix delimiter alignment for content with different display width (e.g., emoji, CJK, ANSI colors). Called only when alignDelimiters is not false.

### Request Example
```js
import {markdownTable} from 'markdown-table'

markdownTable([
  ['Alpha', 'B'],
  ['C', 'Delta']
])
```

### Response
#### Success Response
Returns a string containing the markdown table.

#### Response Example
```
| Alpha | B     |
| ----- | ----- |
| C     | Delta |
```

### Examples
#### align: ['l', 'c', 'r']
```js
markdownTable(
  [
    ['Beep', 'No.', 'Boop'],
    ['beep', '1024', 'xyz'],
    ['bar', '45', 'lmno']
  ],
  {align: ['l', 'c', 'r']}
)
```
Output:
```
| Beep |  No. | Boop |
| :--- | :--: | ---: |
| beep | 1024 |  xyz |
| bar  |  45  | lmno |
```

#### alignDelimiters: false
```js
markdownTable(
  [
    ['Branch', 'Commit', 'Beep'],
    ['main', '0123456789abcdef', 'beep']
  ],
  {alignDelimiters: false, align: ['', 'l', 'c']}
)
```
Output:
```
| Branch | Commit | Beep |
| - | :- | :-: |
| main | 0123456789abcdef | beep |
```

#### delimiterStart: false
```js
markdownTable(
  [
    ['Branch', 'Commit'],
    ['main', '0123456789abcdef']
  ],
  {delimiterStart: false}
)
```
Output:
```
Branch | Commit           |
------ | ---------------- |
main   | 0123456789abcdef |
```

#### delimiterEnd: false
```js
markdownTable(
  [
    ['Branch', 'Commit'],
    ['main', '0123456789abcdef']
  ],
  {delimiterEnd: false}
)
```
Output:
```
| Branch | Commit
| ------ | ----------------
| main   | 0123456789abcdef
```

#### padding: false
```js
markdownTable(
  [
    ['Branch', 'Commit'],
    ['main', '0123456789abcdef']
  ],
  {padding: false}
)
```
Output:
```
|Branch|Commit          |
|------|----------------|
|main  |0123456789abcdef|
```

#### stringLength
```js
import stringWidth from 'string-width'

markdownTable(
  [
    ['Alpha', 'Bravo'],
    ['中文', 'Charlie'],
    ['👩‍❤️‍👩', 'Delta']
  ],
  {stringLength: stringWidth}
)
```
Output:
```
| Alpha | Bravo   |
| ----- | ------- |
| 中文  | Charlie |
| 👩‍❤️‍👩    | Delta   |
```

### Notes
- Multi-character alignment tokens are accepted; only the lowercased first character matters (e.g., 'left' works like 'l').
- Combining delimiterStart: false and delimiterEnd: false could create fragile structures that aren't understandable to some markdown parsers.
```

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

### Options type definition

Source: https://github.com/wooorm/markdown-table/blob/main/_autodocs/types.md

The Options type defines the configuration object used to customize table generation, including alignment, delimiters, and padding settings.

```ts
export type Options = {
    /**
     * Whether to align the delimiters (default: `true`);
     * they are aligned by default: ...
     * Pass `false` to make them staggered: ...
     */
    alignDelimiters?: boolean | null | undefined;
    /**
     * How to align columns (default: `''`);
     * one style for all columns or styles for their respective columns;
     * each style is either `'l'` (left), `'r'` (right), or `'c'` (center);
     * other values are treated as `''`, which doesn't place the colon in the
     * alignment row but does align left;
     * *only the lowercased first character is used, so `Right` is fine.*
     */
    align?: ReadonlyArray<string | null | undefined> | string | null | undefined;
    /**
     * Whether to end each row with the delimiter (default: `true`). ...
     */
    delimiterEnd?: boolean | null | undefined;
    /**
     * Whether to begin each row with the delimiter (default: `true`). ...
     */
    delimiterStart?: boolean | null | undefined;
    /**
     * Whether to add a space of padding between delimiters and cells
     * (default: `true`). ...
     */
    padding?: boolean | null | undefined;
    /**
     * Function to detect the length of table cell content (optional); ...
     */
    stringLength?: ((value: string) => number) | null | undefined;
};
```

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

### MarkdownTableOptions

Source: https://github.com/wooorm/markdown-table/blob/main/_autodocs/types.md

Deprecated type alias for Options. Kept for backward compatibility and scheduled for removal in the next major release. New code should use Options.

```APIDOC
## MarkdownTableOptions

### Description
Deprecated type alias for Options. Kept for backward compatibility and scheduled for removal in the next major release. New code should use Options.

### Type Definition
```ts
export type MarkdownTableOptions = Options;
```

### Deprecation
This type is deprecated. Use `Options` instead.
```

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

### Custom column alignment with align

Source: https://github.com/wooorm/markdown-table/blob/main/_autodocs/configuration.md

Configures specific column alignment using the align option with 'l', 'c', and 'r' tokens.

```js
markdownTable(
  [
    ['Beep', 'No.', 'Boop'],
    ['beep', '1024', 'xyz'],
    ['bar', '45', 'lmno']
  ],
  {align: ['l', 'c', 'r']}
)
// | Beep |  No. | Boop |
// | :--- | :--: | ---: |
// | beep | 1024 |  xyz |
// | bar  |  45  | lmno |
```

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

### TypeScript signature for markdownTable

Source: https://github.com/wooorm/markdown-table/blob/main/_autodocs/api-reference/markdown-table.md

The full TypeScript signature for the markdownTable function as defined in index.d.ts.

```ts
export function markdownTable(
  table: ReadonlyArray<ReadonlyArray<string | null | undefined>>,
  options?: Readonly<Options> | null | undefined
): string
```

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

### JSDoc signature for markdownTable

Source: https://github.com/wooorm/markdown-table/blob/main/_autodocs/api-reference/markdown-table.md

The JSDoc signature for the markdownTable function as defined in index.js.

```js
/**
 * @param {ReadonlyArray<ReadonlyArray<string | null | undefined>>} table
 *   Table data (matrix of strings).
 * @param {Readonly<Options> | null | undefined} [options]
 *   Configuration (optional).
 * @returns {string}
 *   Result.
 */
export function markdownTable(table, options)
```

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

### Disable delimiter padding with alignDelimiters: false

Source: https://github.com/wooorm/markdown-table/blob/main/_autodocs/configuration.md

Disables delimiter padding, resulting in a compact alignment row with minimal hyphen usage.

```js
markdownTable(
  [
    ['Branch', 'Commit', 'Beep'],
    ['main', '0123456789abcdef', 'beep']
  ],
  {alignDelimiters: false, align: ['', 'l', 'c']}
)
// | Branch | Commit | Beep |
// | - | :- | :-: |
// | main | 0123456789abcdef | beep |
```

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

### Disable cell padding with padding: false

Source: https://github.com/wooorm/markdown-table/blob/main/_autodocs/configuration.md

Removes extra spaces around cell content.

```js
markdownTable(
  [
    ['Branch', 'Commit'],
    ['main', '0123456789abcdef']
  ],
  {padding: false}
)
// |Branch|Commit          |
// |------|----------------|
// |main  |0123456789abcdef|
```

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

### Handle complex characters with stringLength

Source: https://github.com/wooorm/markdown-table/blob/main/_autodocs/configuration.md

Uses a custom stringLength function to correctly align cells containing characters with non-standard visual widths.

```js
import stringWidth from 'string-width'

markdownTable(
  [
    ['Alpha', 'Bravo'],
    ['中文', 'Charlie'],
    ['👩‍❤️‍👩', 'Delta']
  ],
  {stringLength: stringWidth}
)
// | Alpha | Bravo   |
// | ----- | ------- |
// | 中文  | Charlie |
// | 👩‍❤️‍👩    | Delta   |
```
Tokens:
Raw