mdast-util-pipe-table

Utilities to convert the pipe-table micromark tokens into mdast nodes, and back to markdown.

This package defines the canonical AST shape for pipe-table nodes.

Vertical Cell Syntax

Pipe Table allows table cells to be written vertically, one per line, instead of being confined to a single row.

| a
    | b
    | c

This represents one table row with three cells.

Vertical layout makes tables easier to edit, reorder, and review in diffs, and enables multi-line and block-level content inside cells.

For the complete syntax specification, see: docs/syntax.md

Install

npm install mdast-util-pipe-table

Usage

Parsing (from markdown)

import { fromMarkdown } from 'mdast-util-from-markdown'
import { pipeTable, pipeTableFromMarkdown } from 'mdast-util-pipe-table'

const tree = fromMarkdown('| a | b | c', {
  extensions: [pipeTable()],
  mdastExtensions: [pipeTableFromMarkdown()]
})
console.log(tree);

• pipeTable() is a micromark syntax extension (re-exported from micromark-extension-pipe-table).
• pipeTableFromMarkdown() is an mdast extension for mdast-util-pipe-table.

Serializing (to markdown)

import { toMarkdown } from 'mdast-util-to-markdown'
import { pipeTableToMarkdown } from 'mdast-util-pipe-table'

// const tree = <your mdast tree>
const markdown = toMarkdown(tree, {
    extensions: [pipeTableToMarkdown()]
})
console.log(markdown);

Options

pipeTableFromMarkdown

pipeTableFromMarkdown({
    /**
     * Inline parsing extensions used for pipe-table cell content.
     * Use this to enable features such as GFM strikethrough (`~~`).
     */
    inline?: {
        /** micromark extensions (e.g. `[gfm()]`) */
        extensions?: MicromarkExtension[]
        /** mdast extensions for from-markdown (e.g. `[gfmFromMarkdown()]`) */
        mdastExtensions?: MdastFromMarkdownExtension[]
    }

    /**
     * Block parsing extensions used when a cell is parsed as block content
     * (lists, headings, blockquotes, etc).
     *
     * If omitted, `inline` options are used as a fallback.
     * `pipeTable` itself is never passed to avoid nested tables.
     */
    block?: {
        /** micromark extensions */
        extensions?: MicromarkExtension[]
        /** mdast extensions for from-markdown */
        mdastExtensions?: MdastFromMarkdownExtension[]
    }
})

pipeTableToMarkdown

pipeTableToMarkdown currently does not expose additional options.

AST Types

This package exports the canonical mdast node types:

• PipeTable
• PipeTableRow
• PipeTableCell
• PipeTableDelimiterRow
• Align

Other packages (hast-util-pipe-table, type augmentations, etc.) should import these types from here.

Related Packages

• micromark-extension-pipe-table Micromark syntax extension that tokenizes the pipe-table syntax.
• hast-util-pipe-table Transforms pipe-table mdast nodes into HTML (hast).
• remark-pipe-table Remark plugin that wires all pipe-table extensions together.

License

MIT