Tablemark NPM | npm.io

tablemark ·

Generate markdown tables from JSON data.

Renders arrays of objects as markdown tables, complete with configuration for renaming columns and left, center, or right-aligning them.

installation

yarn add tablemark

# or

npm install tablemark

usage

import tablemark from "tablemark"

tablemark([
  { name: "Bob", age: 21, isCool: false },
  { name: "Sarah", age: 22, isCool: true },
  { name: "Lee", age: 23, isCool: true }
])

// | Name  | Age   | Is cool |
// | :---- | :---- | :------ |
// | Bob   | 21    | false   |
// | Sarah | 22    | true    |
// | Lee   | 23    | true    |

... displays as:

Name	Age	Is cool
Bob	21	false
Sarah	22	true
Lee	23	true

api

tablemark (input: InputData, options?: TablemarkOptions): string

Arguments

InputData input: the data to table-ify
- an array of objects or iterables

TablemarkOptions options:

key	type	default	description
`columns`	`Array<string \\| ColumnDescriptor>`	-	Array of column descriptors.
`caseHeaders`	`boolean`	`true`	Sentence case headers derived from keys.
`toCellText`	`(input: unknown) => string`	-	Provide a custom "toString" function.
`padHeaderSeparator`	`boolean`	`true`	Whether to pad gutters of the header separator (alignment) row.
`wrapWidth`	`number`	`Infinity`	Wrap cell text at this length.
`wrapWithGutters`	`boolean`	`false`	Add sides (`\\| <content> \\|`) to wrapped rows.
`lineEnding`	`string`	`"\n"`	String used at end-of-line.

The columns array can either contain objects, in which case their name and align properties will be used to alter the display of the column in the table, or any other type which will be coerced to a string if necessary and used as a replacement for the column name.

Returns

string: the resulting markdown formatted table

Throws

TypeError: when input is not iterable (e.g., an array) TypeError: when an unknown column alignment option is provided

`options.columns`

tablemark(
  [
    { name: "Bob", age: 21, isCool: false },
    { name: "Sarah", age: 22, isCool: true },
    { name: "Lee", age: 23, isCool: true }
  ],
  {
    columns: [
      "first name",
      { name: "how old", align: "center" },
      "are they cool"
    ]
  }
)

// | first name | how old | are they cool |
// | :--------- | :-----: | :------------ |
// | Bob        |   21    | false         |
// | Sarah      |   22    | true          |
// | Lee        |   23    | true          |

... displays as:

first name	how old	are they cool
Bob	21	false
Sarah	22	true
Lee	23	true

`options.padHeaderSeparator`

tablemark(
  [
    { name: "Bob", age: 21, isCool: false },
    { name: "Sarah", age: 22, isCool: true },
    { name: "Lee", age: 23, isCool: true }
  ],
  {
    columns: [{ align: "left" }, { align: "center" }, { align: "right" }]
  }
)

// | first name | how old | are they cool |
// |:-----------|:-------:|--------------:|
// | Bob        |   21    | false         |
// | Sarah      |   22    | true          |
// | Lee        |   23    | true          |

... displays as:

first name	how old	are they cool
Bob	21	false
Sarah	22	true
Lee	23	true

`options.toCellText`

tablemark(
  [
    { name: "Bob", pet_owner: true, studying: false },
    { name: "Sarah", pet_owner: false, studying: true },
    { name: "Sarah", pet_owner: true, studying: true }
  ],
  {
    toCellText,
    columns: [{ align: "left" }, { align: "center" }, { align: "center" }]
  }
)

function toCellText(v) {
  if (v === true) return "✔"
  if (!v) return ""
  return v
}

// | Name  | Pet owner | Studying |
// | :---- | :-------: | :------: |
// | Bob   |     ✔︎     |          |
// | Sarah |           |    ✔     |
// | Lee   |     ✔     |    ✔     |

`options.wrapWidth`

Set options.wrapWidth to wrap any content at that length onto a new adjacent line:

tablemark(
  [
    { star: false, name: "Benjamin" },
    { star: true, name: "Jet Li" }
  ],
  { wrapWidth: 5 }
)

// | Star  | Name  |
// | :---- | :---- |
// | false | Benja |
//           min
// | true  | Jet   |
//           Li

To output valid GitHub Flavored Markdown a cell must not contain newlines. Consider replacing those with <br /> (e.g., using options.toCellText).

`options.wrapWithGutters`

Enable wrapWithGutters to add pipes on all lines:

tablemark(
  [
    { star: false, name: "Benjamin" },
    { star: true, name: "Jet Li" }
  ],
  { wrapWidth: 5, wrapWithGutters: true }
)

// | Star  | Name  |
// | :---- | :---- |
// | false | Benja |
// |       | min   |
// | true  | Jet   |
// |       | Li    |

contributing

Search the issues if you come across any trouble, open a new one if it hasn't been posted, or, if you're able, open a pull request. Contributions of any kind are welcome in this project.

The following people have already contributed their time and effort: