wooorm / markdown-table

Generate a markdown (GFM) table

markdown-table

Generate a markdown (GFM) table.

Contents

• What is this?
• When should I use this?
• Install
• Use
• API
  • markdownTable(table[, options])
• Types
• Compatibility
• Security
• Inspiration
• Contribute
• License

What is this?

This is a simple package that takes table data and generates a GitHub flavored markdown (GFM) table.

When should I use this?

You can use this package when you want to generate the source code of a GFM table from some data.

This is a simple solution in that it doesn’t handle escapes or HTML or any of that. For a complete but heavier solution, build an AST and serialize it with mdast-util-to-markdown (with mdast-util-gfm).

Install

This package is ESM only. In Node.js (version 14.14+, 16.0+), install with npm:

npm install markdown-table

In Deno with esm.sh:

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

In browsers with esm.sh:

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

Use

Typical usage (defaults to align left):

import {markdownTable} from 'markdown-table'

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

Yields:

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

With align:

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

Yields:

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

API

This package exports the identifier markdownTable. There is no default export.

markdownTable(table[, options])

Generate a markdown table from table data (matrix of strings).

options

Configuration (optional).

options.align

One style for all columns, or styles for their respective columns (string or Array<string>). 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.

options.padding

Whether to add a space of padding between delimiters and cells (boolean, default: true).

When true, there is padding:

| Alpha | B     |
| ----- | ----- |
| C     | Delta |

When false, there is no padding:

|Alpha|B    |
|-----|-----|
|C    |Delta|

options.delimiterStart

Whether to begin each row with the delimiter (boolean, default: true).

👉 Note: please don’t use this: it could create fragile structures that aren’t understandable to some markdown parsers.

When true, there are starting delimiters:

| Alpha | B     |
| ----- | ----- |
| C     | Delta |

When false, there are no starting delimiters:

Alpha | B     |
----- | ----- |
C     | Delta |

options.delimiterEnd

Whether to end each row with the delimiter (boolean, default: true).

👉 Note: please don’t use this: it could create fragile structures that aren’t understandable to some markdown parsers.

When true, there are ending delimiters:

| Alpha | B     |
| ----- | ----- |
| C     | Delta |

When false, there are no ending delimiters:

| Alpha | B
| ----- | -----
| C     | Delta

options.alignDelimiters

Whether to align the delimiters (boolean, default: true). By default, they are aligned:

| Alpha | B     |
| ----- | ----- |
| C     | Delta |

Pass false to make them staggered:

| Alpha | B |
| - | - |
| C | Delta |

options.stringLength

Function to detect the length of table cell content (Function, default: s => s.length). This is used when aligning the delimiters (|) between table cells. Full-width characters and emoji mess up delimiter alignment when viewing the markdown source. To fix this, you can pass this function, which receives the cell content and returns its “visible” size. Note that what is and isn’t visible depends on where the text is displayed.

Without such a function, the following:

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

Yields:

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

With string-width:

import stringWidth from 'string-width'

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

Yields:

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

Types

This package is fully typed with TypeScript. It exports the additional type Options.

Compatibility

This package is at least compatible with all maintained versions of Node.js. As of now, that is Node.js 14.14+ and 16.0+. It also works in Deno and modern browsers.

Security

This package is safe.

Inspiration

The original idea and basic implementation was inspired by James Halliday’s text-table library.

Contribute

Yes please! See How to Contribute to Open Source.

License

MIT © Titus Wormer

markdown-table's Issues

Jagged arrays

Does your library handle jagged arrays?

Thank you

package won't import on node v14.16.1

Issue

The package will not import on node version 14.16.1 (Windows 10)

import { markdownTable } from 'markdown-table';

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

Result

TypeScript types

Would you be open to having TS types in this repo if I could create them?

ESM not working as expected

Tried to upgrade to v3 in a project that is using TypeScript to import this file and I'm seeing the following error:

Error [ERR_REQUIRE_ESM]: Must use import to load ES Module: .../node_modules/markdown-table/index.js
require() of ES modules is not supported.

I played around with renaming the main file with .cjs and .mjs and ran into other issues.

Running Node v15.11.0

Typescript types are too restrictive

In the serialize method, anything that's not null or undefined is going to get passed to the String constructor so any value that implements a toString() method should be acceptable as a table cell value.

Minimum of 3 characters for alignment row cells

Many markdown software requires at least 3 dashes when processing table

Value with line break will not be transformed as expected

With following value, markdown-table will not be transformed as expected. Can you spare some time to give me some suggestions?

const rawData = [ [ '属性', '说明', '类型', '默认值' ],
  [ 'params',
    '',
    'object',
    '{\n  id: {\n    label: "标签ID",\n    type: "input"\n  },\n  categoryId: {\n    label: "分类",\n    type: "tree",\n    options: []\n  },\n  status: {\n    label: "状态",\n    type: "select",\n    options: {\n      0: "下线",\n      1: "上线"\n    }\n  },\n  startDay: {\n    label: "开始日期",\n    type: "date"\n  },\n  audit: {\n    label: "需要审核",\n    type: "select",\n    selectNoAll: true,\n    defaultValue: "0",\n    options: {\n      0: "否",\n      1: "是"\n    }\n  },\n  updateUser: {\n    label: "更新者",\n    type: "input",\n    placeholder: "请输入工号或花名搜索"\n  }\n}' ],
  [ 'paramValue', '', 'object', '' ],
  [ 'btns', '', 'array', '' ],
  [ 'onQuerySubmit', '', 'func', '' ],
  [ 'extraCpts', '', 'array', '' ],
  [ 'preRender', '', 'bool', '' ] ]

hallo, i'm rewrite with ts this repo, added support for cjs and esm, please consider pull request

forked: https://github.com/halo951/markdown-table

i saw your repo not open pull request with other repo, so I can only give you an issue, hope you can handle this request.

Width for chinese characters is incorrectly calculated

Execute this program

const table = require('markdown-table');

console.log(table([
    ['First', 'Second'],
    ['Hello', 'world'],
    ['會意字', 'world'],
    ['Hello', 'world'],
]))

Expected result:

| First   | Second |
| ------- | ------ |
| Hello   | world  |
| 會意字   | world  |
| Hello   | world  |

Actual result:

| First | Second |
| ----- | ------ |
| Hello | world  |
| 會意字   | world  |
| Hello | world  |

Configuration:
[email protected]

Bold max row/col value?

This is maybe a super-specific use-case, but for scientific data/experiments, it's often helpful to make the maximum value in a row or column bold for visibility. Maybe that could be an option?

Stop showing colons when align right/center

Hello, this might be pretty rudimentary, but figured I'd ask. I'm using this to create more of a text-table that gets put in a pre-formatted block (where it ends up doesn't support MD tables) rathen than to create Markdown formatting.

So, I don't really need the : to do alignment, but still want to use alignment. The : ends up throwing off the otherwise clean look. This is easy/quick to fix:

https://github.com/wooorm/markdown-table/blob/master/index.js#L21

var COLOR = ':'

to

var COLON = '-'

But, is there a better way to stop showing : when alignment is right/center?

Doesn't seem to be from my reviewing the code. Not sure if it's worth a PR to add a passable option given using this as a text-table tool is not the direct purpose of the module? Let me know!