DOCSEARCHbyAlgolia
Submit Docs

markdown-table

repository·main·Indexed 43 days ago

https://github.com/wooorm/markdown-table

A lightweight utility for generating GitHub Flavored Markdown (GFM) tables from a matrix of strings. Version 3.0.4 supports custom column alignment, padding control, and custom string length functions to handle emojis and full-width characters.

Tokens
1K
Snippets
4
Records
5
Agent score
5%

What's inside markdown-table

  1. Install markdown-table

    main

    This package is ESM only. Choose the installation method based on your runtime:

    Node.js

    Requires version 14.14+ or 16.0+.

    npm install markdown-table

    Deno

    Use esm.sh:

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

    Browsers

    Use esm.sh with the ?bundle query parameter:

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

  2. Generate a GFM table with markdownTable()

    main

    The markdownTable function takes a matrix of strings (an array of arrays) and generates a GitHub Flavored Markdown (GFM) table. By default, columns are aligned to the left.

    Basic Usage

    import {markdownTable} from 'markdown-table'

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

    Custom Alignment

    You can specify alignment for each column using the align option. Values can be a single string for all columns or an array of strings. Supported values are 'l' (left), 'c' (center), and 'r' (right). Note that the function is case-insensitive (e.g., 'Right' works).

    markdownTable(
  [
    ['Beep', 'No.', 'Boop'],
    ['beep', '1024', 'xyz'],
    ['boop', '3388450', 'tuv']
  ],
  {align: ['l', 'c', 'r']}
)
    import {markdownTable} from 'markdown-table'

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

  3. Handle emojis and full-width characters with stringLength

    main

    By default, markdownTable uses .length to calculate cell width, which can cause misalignment when using emojis or non-Latin characters (like Chinese). To ensure delimiters (|) align correctly in the source code, provide a custom stringLength function that returns the 'visible' width of the string, such as the one provided by the string-width package.

    import stringWidth from 'string-width'

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

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

  4. Configure markdownTable options

    main

    The markdownTable(table, options) function accepts an optional options object to customize the output format.

    options.align (string | Array<string>)

    One style for all columns, or styles for their respective columns.

    • 'l': left
    • 'c': center
    • 'r': right
    • Other values are treated as '' (align left without a colon in the delimiter row).

    options.padding (boolean, default: true)

    Whether to add a space of padding between delimiters and cells.

    options.delimiterStart (boolean, default: true)

    Whether to begin each row with the delimiter (|).

    Note: Using false may create fragile structures for some markdown parsers.

    options.delimiterEnd (boolean, default: true)

    Whether to end each row with the delimiter (|).

    Note: Using false may create fragile structures for some markdown parsers.

    options.alignDelimiters (boolean, default: true)

    Whether to align the delimiters (|) between table cells. If false, delimiters will be staggered.

    options.stringLength (Function, default: s => s.length)

    A function to detect the visible length of table cell content. This is useful for handling full-width characters or emojis that cause misalignment in the markdown source.

    Example using string-width:

    import stringWidth from 'string-width'

markdownTable(data, {stringLength: stringWidth})

  5. Generate a markdown table with `markdownTable()`

    main

    Use the markdownTable function to convert a 2D array (matrix) of strings into a GFM-compliant markdown table string. The function accepts a table data array and an optional configuration object.

    import { markdownTable } from 'markdown-table'

const table = [
  ['Alpha', 'Bravo'],
  ['Charlie', 'Delta']
]

const markdown = markdownTable(table)