markdown-it-pipe-table

A markdown-it plugin that adds a flexible pipe-based table syntax, designed to support multi-line cells, vertical cell layout, and block-level content inside table cells.

This plugin is intended to be used together with editors and preview environments such as VS Code, where the default GFM table syntax is often too restrictive.

Features

• Adds pipe-table syntax support to markdown-it
• Supports:
  • Largely compatible with GFM tables (pipe-based syntax, delimiter rows, column alignment, etc.)
  • Multi-line table cells
  • Vertical cell layout
  • Block-level content inside cells (lists, code blocks, blockquotes, headings, etc.)
  • Multiple <tbody> sections
• Can disable markdown-it’s built-in GFM table rule to avoid conflicts

👉 VS Code users: Use the companion extension Pipe Table Preview for VS Code to get proper pipe-table rendering in the built-in Markdown preview.

Installation

npm install markdown-it-pipe-table

Usage

import markdownit from "markdown-it";
import pipeTable from 'markdown-it-pipe-table'

const md = markdownit();
md.use(pipeTable);

const src = `\
| header 1 | header 2
|:-|-:
| cell A | cell B
`;

console.log(md.render(src));

Output:

<table>
    <thead>
        <tr>
            <th>header 1</th>
            <th>header 2</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td class="cell-left">cell A</td>
            <td class="cell-right">cell B</td>
        </tr>
    </tbody>
</table>

Syntax

Simple table

| a | b
|-
| c | d

Column alignment

| left | center | right
|:-----|:------:|------:
| a    | b      | c

• |:- → left
• |:-: → center
• |-: → right

Alignment is emitted as CSS classes on <td> elements.

Multi-line cells

| item
  description line 1
  description line 2
|-
| next

Vertical cell layout

Cells can be written vertically by indenting lines that start with |:

| a
    | b
    | c
|-
| d
    | e
    | f

This produces a single row with multiple cells.

Block-level content inside cells

If a cell’s content is consistently indented, it will be parsed as block content:

| list
  - apple
  - banana
|-
| text

Multiple <tbody> sections

Each delimiter row (|-) starts a new <tbody>:

| h1 | h2
|-
| a  | b
|-
| c  | d

For a complete and implementation-agnostic description of the syntax, see: Pipe Table Syntax (unified / remark)

Note: that this document describes the syntax only. Implementation-specific behavior (such as editor preview integration) is documented in this package.

Options

type PipeTableOptions = {
  /**
   * Alignment class prefix.
   * default: "cell-"
   * -> "cell-left" / "cell-right" / "cell-center"
   */
  classPrefix?: string

  /**
   * Use logical alignment classes (start / center / end)
   * default: false
   */
  useLogicalAlignment?: boolean

  /**
   * Disable markdown-it built-in table rule.
   * default: true
   */
  disableMarkdownItTable?: boolean

  /**
   * Tab size used for indentation column counting.
   * default: 4
   */
  tabSize?: number
}

Design Notes

• This plugin intentionally does not reuse GFM table parsing
• Parsing is block-based and indentation-aware
• The implementation prioritizes:
  • predictable parsing
  • editor preview compatibility
  • extensibility for future Markdown tooling

Related projects

• remark-pipe-table A remark plugin that adds the same pipe-table syntax to unified / remark pipelines.

License

MIT