markdown-it-table
Plugin for markdown-it markdown parser, adding table with nested block syntax support.
These tables are neither CommonMark nor GFM. CommonMark has no table syntax, and GFM cells hold inline content only, so GitHub renders
| - item |as the text- itemwhere this plugin renders a list. The HTML differs as well, as listed under Differences from markdown-it's table.
Install
$ yarn add markdown-it-table
Usage
markdown-it's default preset has its own table rule, and that rule runs before this plugin. Disable it, or start from the commonmark preset, which leaves it off.
import MarkdownIt from "markdown-it";
import { markdownItTable } from "markdown-it-table";
const md = new MarkdownIt().disable("table").use(markdownItTable);
With the commonmark preset, new MarkdownIt("commonmark").use(markdownItTable) is enough. That preset also sets html: true, so raw HTML in the source reaches the output. For untrusted input, pass { html: false } with it or use the default preset. CommonJS works with const { markdownItTable } = require("markdown-it-table");. The plugin takes no options.
Syntax
A table is a header row, a delimiter row, then one line per body row. In the delimiter row, :-- aligns a column left, :-: centers it and --: aligns it right. A line without a | ends the table, and so does a line that starts another block, such as a blockquote, list, heading, fence or HTML block.
The plugin parses each body cell as markdown blocks, so a cell can hold a list, a blockquote, a heading or a thematic break.
| Syntax | Cell |
| ------ | ------------- |
| List | - item |
| Quote | > quoted text |
renders as
|
Syntax |
Cell |
|---|---|
|
List |
|
|
Quote |
|
HTML
<table>
<tr>
<th>
<p>Syntax</p>
</th>
<th>
<p>Cell</p>
</th>
</tr>
<tr>
<td>
<p>List</p>
</td>
<td>
<ul>
<li>item</li>
</ul>
</td>
</tr>
<tr>
<td>
<p>Quote</p>
</td>
<td>
<blockquote>
<p>quoted text</p>
</blockquote>
</td>
</tr>
</table>
Cells
- Header cells take inline markdown only.
- A row is one line, so a cell's content has to fit on it.
- The plugin ignores the spaces and tabs around a cell's content, so a padded cell never turns into an indented code block.
- A cell holding only a list marker, like
| - |or| 1. |, renders as that text. \|and a|inside a code span don't split a cell.
Differences from markdown-it's table
- Plain text in a cell goes in a
<p>, header cells included. - There is no
<thead>or<tbody>. Rows go straight into<table>. - Rows keep the cells they're written with. markdown-it pads short rows and drops extra cells to match the header.
- A
|inside a code span stays in the cell. markdown-it splits the cell there.