markdown-it-multimd-table

MultiMarkdown table syntax plugin for markdown-it markdown parser

Intro

When writing table in Markdown syntax, we have to fallback to write raw HTML tags, if we just need some advanced attribute like colspan. MultiMarkdown is an extended Markdown spec covering fancy features. It has defined some complete and clear rules for advanced Markdown table syntax, and aims to be compatible to basic table syntax as possible.

markdown-it is a powerful and widely-used Markdown compiler, in native it supports basic table syntax only. It allows plugins to expand it capability, and this plugin replaced the original table parser in markdown-it to support MultiMarkdown table syntax.

For now, these extended features are provided:

• Cells spanning multiple columns
• Cells spanning multiple rows (optional)
• Grouped table header rows or data rows
• Table caption above or below the table
• Blocked elements (lists, codes, paragraphs...) in table (optional)
• Table header not required (optional)

Noted: the plugin is not a re-written of MultiMarkdown to deploy on markdown-it, it will generate HTML different from MultiMarkdown official compiler in some corner cases. This plugin try to follow the rule defined in MultiMarkdown User's Guide as possible. If some case is reasonable but behaves strangely, please pose an issue for that.

Usage

// defaults
var md = require('markdown-it')()
            .use(require('markdown-it-multimd-table'));

// full options list (same to defaults)
var md = require('markdown-it')()
            .use(require('markdown-it-multimd-table'), {
              multiline:  false,
              rowspan:    false,
              headerless: false,
            });

md.render(/*...*/)

To simply test this plugin, you can do these in terminal:

$ mkdir markdown-it-multimd-table
$ cd markdown-it-multimd-table
$ npm install markdown-it-multimd-table --prefix .
$ vim test.js

    var md = require('markdown-it')()
                .use(require('markdown-it-multimd-table'));

    const exampleTable =
    "|             |          Grouping           || \n" +
    "First Header  | Second Header | Third Header | \n" +
    " ------------ | :-----------: | -----------: | \n" +
    "Content       |          *Long Cell*        || \n" +
    "Content       |   **Cell**    |         Cell | \n" +
    "                                               \n" +
    "New section   |     More      |         Data | \n" +
    "And more      | With an escaped '\\|'       || \n" +
    "[Prototype table]                              \n";

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

$ node test.js > test.html
$ firefox test.html

And you will see the rendered table in the browser:

Prototype table

	Grouping
First Header	Second Header	Third Header
Content	Long Cell
Content	Cell	Cell
New section	More	Data
And more	With an escaped '|'

Noted that GitHub filters out style property, so the example displays with the obsolete align property. But in actual this plugin outputs style property with text-align CSS attribute.

Multiline (optional)

A backslash at end to join cell contents with the following lines.
This feature is contributed by Lucas-C.

|   Markdown   | Rendered HTML |
|--------------|---------------|
|    *Italic*  | *Italic*      | \
|              |               |
|    - Item 1  | - Item 1      | \
|    - Item 2  | - Item 2      |
|    ```python | ```python       \
|    .1 + .2   | .1 + .2         \
|    ```       | ```           |

If this option is enabled, code above would be parsed as:

Markdown	Rendered HTML
*Italic*	Italic
- Item 1 - Item 2	Item 1 Item 2
```python .1 + .2 ```	.1 + .2

Rowspan (optional)

^^ in a cell indicates it should be merged with the cell above.
This feature is contributed by pmccloghrylaing.

Stage | Direct Products | ATP Yields
----: | --------------: | ---------:
Glycolysis | 2 ATP ||
^^ | 2 NADH | 3--5 ATP |
Pyruvaye oxidation | 2 NADH | 5 ATP |
Citric acid cycle | 2 ATP ||
^^ | 6 NADH | 15 ATP |
^^ | 2 FADH2 | 3 ATP |
**30--32** ATP |||
[Net ATP yields per hexose]

If this option is enabled, code above would be parsed as:

Net ATP yields per hexose

Stage	Direct Products	ATP Yields
Glycolysis	2 ATP
2 NADH	3–5 ATP
Pyruvaye oxidation	2 NADH	5 ATP
Citric acid cycle	2 ATP
6 NADH	15 ATP
2 FADH2	3 ATP
30–32 ATP

Headerless (optional)

Table header can be eliminated.

|--|--|--|--|--|--|--|--|
|♜|  |♝|♛|♚|♝|♞|♜|
|  |♟|♟|♟|  |♟|♟|♟|
|♟|  |♞|  |  |  |  |  |
|  |♗|  |  |♟|  |  |  |
|  |  |  |  |♙|  |  |  |
|  |  |  |  |  |♘|  |  |
|♙|♙|♙|♙|  |♙|♙|♙|
|♖|♘|♗|♕|♔|  |  |♖|

If this option is enabled, code above would be parsed as:

♜		♝	♛	♚	♝	♞	♜
	♟	♟	♟		♟	♟	♟
♟		♞
	♗			♟
				♙
					♘
♙	♙	♙	♙		♙	♙	♙
♖	♘	♗	♕	♔			♖

Credits

• MultiMarkdown, Lightweight markup processor to produce HTML, LaTeX, and more.
• markdown-it, Markdown parser, done right. 100% CommonMark support, extensions, syntax plugins & high speed.

License

This software is licensed under the MIT license © RedBug312.