markdown-it-multimd-table-ext

This is a fork of RedBug312's markdown-it-multimd-table, used in the bebras toolchain.*

Below is the original README, slightly modified.


MultiMarkdown table syntax plugin for markdown-it markdown parser

Intro

Markdown specs defines only the basics for tables. When users want common
features like colspan, they must fallback to raw HTML. And writing tables in
HTML is truly lengthy and troublesome.

This plugin extends markdown-it with MultiMarkdown table syntax.
[MultiMarkdown][mmd6] is an extended Markdown spec. It defines clear rules for
advanced Markdown table syntax, while being consistent with original pipe
table; [markdown-it][mdit] is a popular Markdown parser in JavaScript and
allows plugins extending itself.

[mmd6]: https://fletcher.github.io/MultiMarkdown-6/
[mdit]: https://markdown-it.github.io/

The features are provided:
- Cell spans over columns
- Cell spans over rows (optional)
- Divide rows into sections
- Multiple table headers
- Table caption
- Block-level elements such as lists, codes... (optional)
- Omitted table header (optional)
- Vertical alignment
- Overridden horizontal and vertical alignment cell by cell
- More control on lines

Noted that the plugin is not a re-written of MultiMarkdown. This plugin will
behave differently from the official compiler, but doing its best to obey rules
defined in [MultiMarkdown User's Guide][mmd6-table]. Please pose an issue if
there are weird results for sensible inputs.

[mmd6-table]: https://fletcher.github.io/MultiMarkdown-6/syntax/tables.html

Usage

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

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

md.render(/.../)
`

For a quick demo:
`javascript
$ mkdir markdown-it-multimd-table-ext
$ cd markdown-it-multimd-table-ext
$ npm install markdown-it markdown-it-multimd-table-ext --prefix .
$ vim test.js

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

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
`

Here's the table expected on browser:

Noted that GitHub filters out style property, so the example uses align the
obsolete one. However it outputs style="text-align: ..." in actual.

Options

$3

Backslash at end merges with line content below.

Feature contributed by Lucas-C.

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

This is parsed below when the option enabled:

Italic

- Item 1
- Item 2

`python
.1 + .2
`

.1 + .2

$3

^^ indicates cells being merged above.

Feature contributed by pmccloghrylaing.

`markdown
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]
`

This is parsed below when the option enabled:

$3

Table header can be eliminated.

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

This is parsed below when the option enabled:

$3

An empty line separates consecutive table bodies. When disabled, an empty line
always cuts off the tables.

$3

Table id attribute follows the table caption if not labeled. When disabled,
caption without labels cannot generate the attribute.

$3

Allows setting the vertical alignment of columns with syntax embedded in the separator row.

| Top | Bottom | Default |
| ^---- | v----- | ------- |

This sets the vertical alignment of the first two column to top and bottom, respectively.

$3

At the beginning of a cell, you can write [] to set the alignment of the cell. This overrides the default alignment of the column. Both the horizontal and vertical alignment can be set.

| Col 1 | Col 2 | Col 3 | Col 4 |
| --------- | ---------- | ------------ |------------ |
| [^] Top | [v] Bottom | [=] Middle | Content |
| [:-] Left | [-:] Right | [:-:] Center | [-] Default |

Alternatively, one can use the following specifiers for horizontal alignment:

| Col 1 | Col 2 | Col 3 | Col 4 |
| -------- | --------- | ----------- |------------- |
| [<] Left | [>] Right | [><] Center | [<>] Default |

When specifying both horizontal and vertical alignment, the horizontal alignment should be written first. The alignment specifiers can be separated by a comma or a space for better readability.

$3

Whereas a simple | separator indicates a cell boundary, a double vertical bar ‖ in the separator row asks for a line to be drawn.

This adds a left and and right border to the table:

| Col 1 | Col 2 | Col 3 |
‖ ----- | ----- | ----- ‖
| A | B | C |

‖ only has an effect in the separator row and otherwise acts as a normal cell boundary; this adds no line:

‖ Col 1 | Col 2 | Col 3 ‖
| ----- | ----- | ----- |
| A | B | C |

Complementarily, horizontal lines can be inserted in the middle of a table by having a line with hyphens - instead of actual cell contents (column boundaries are also allowed):

‖ Col 1 | Col 2 | Col 3 ‖
| ----- | ----- | ----- |
| A | B | C |
| ----- | ----- | ----- |
| D | E | F |

Build/Contribute

Use make browserify. To publish your fork after updading the package name, use npm publish`.

Credits

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

License

This software is licensed under the [MIT license][license] © RedBug312, jppellet

[license]: https://opensource.org/licenses/mit-license.php