remark-pipe-table

A remark plugin that enables the pipe-table syntax by wiring micromark and mdast extensions together.

This is the recommended entry point when using remark / unified.

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 remark-pipe-table

Usage

Basic usage (Markdown ⇄ Markdown)

import { unified } from 'unified'
import remarkParse from 'remark-parse'
import remarkStringify from 'remark-stringify'
import remarkPipeTable from 'remark-pipe-table'

const file = await unified()
    .use(remarkParse)
    .use(remarkPipeTable)
    .use(remarkStringify)
    .process('| a | b | c')

console.log(String(file))

Output:

| a
    | b
    | c

HTML output

This plugin does not install remark-rehype automatically.

To generate HTML, combine it with remark-rehype and hast-util-pipe-table:

import { unified } from 'unified'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import rehypeStringify from 'rehype-stringify'

import remarkPipeTable from 'remark-pipe-table'
import { pipeTableHandlers } from 'hast-util-pipe-table'

const html = await unified()
    .use(remarkParse)
    .use(remarkPipeTable)
    .use(remarkRehype, {
        handlers: pipeTableHandlers({
            classPrefix: 'text-'
        })
    })
    .use(rehypeStringify)
    .process('| a | b | c')

console.log(String(html))

Using pipe-table together with GFM

When using remark-pipe-table alongside remark-gfm, there are two distinct layers to be aware of:

1. Document-level GFM features (task lists, autolinks, tables, etc.)
2. Inline GFM syntax inside pipe-table cells (such as ~~strikethrough~~)

By default, remark-gfm enables GFM features for the document as a whole, but pipe-table cells are parsed independently.

Therefore, to use GFM inline syntax inside pipe-table cells, you need to explicitly enable it via the autoInjectGfmInlineInCells option.

Example: GFM + pipe-table (with inline GFM inside cells)

import { unified } from 'unified'
import remarkParse from 'remark-parse'
import remarkGfm from 'remark-gfm'
import remarkRehype from 'remark-rehype'
import rehypeStringify from 'rehype-stringify'

import remarkPipeTable from 'remark-pipe-table'
import { pipeTableHandlers } from 'hast-util-pipe-table'

const md = `
| header1 | header2
|-
| cell1
    | ~~cell2~~
`

const html = await unified()
  .use(remarkParse)
  // Enable GFM for the whole document (task lists, autolinks, etc.)
  .use(remarkGfm)
  // Enable GFM inline syntax inside pipe-table cells (opt-in)
  .use(remarkPipeTable, {
    autoInjectGfmInlineInCells: true
  })
  .use(remarkRehype, {
    handlers: pipeTableHandlers({ classPrefix: 'cell-' })
  })
  .use(rehypeStringify)
  .process(md)

console.log(String(html))

Output (excerpt):

<td><del>cell2</del></td>

Notes

• preferPipeTableOverGfmTable defaults to true, so lines starting with | are handled by pipe-table before GFM tables.
• autoInjectGfmInlineInCells is disabled by default. Enable it only if you want GFM inline syntax (such as ~~strikethrough~~) to work inside pipe-table cells.
• This option does not enable GFM globally. To enable full GFM support, you still need to use remark-gfm.

Options

export type RemarkPipeTableOptions = {
    /**
     * Prefer pipe-table over GFM tables when both are enabled.
     *
     * When true, lines starting with `|` are captured by pipe-table
     * before `remark-gfm`'s table handling.
     *
     * Default: true
     */
    preferPipeTableOverGfmTable?: boolean

    /**
     * Enable GFM inline syntax (e.g. `~~strikethrough~~`)
     * inside pipe-table cells.
     *
     * Default: false
     */
    autoInjectGfmInlineInCells?: boolean

    /**
     * Options passed to `pipeTableFromMarkdown()`,
     * including inline parsing extensions for cell content.
     */
    fromMarkdown?: Parameters<typeof pipeTableFromMarkdown>[0]
}

Related Packages

• micromark-extension-pipe-table Micromark syntax extension that tokenizes the pipe-table syntax.
• mdast-util-pipe-table Converts pipe-table tokens into mdast nodes and defines the canonical AST shape.
• hast-util-pipe-table Transforms pipe-table mdast nodes into HTML (hast).

Related projects

• markdown-it-pipe-table
  A markdown-it plugin that adds the same pipe-table syntax for editor and preview environments such as VS Code.

License

MIT