Micromark Extension Gridtables
Micormark extension to parse markdown gridtables.
Status
Grid Tables
What is this?
This package contains extensions that add support for gridtables to micromark.
When to use this
These tools are all low-level.
In many cases, you want to use @adobe/remark-gridtables with remark instead.
When working with mdast-util-from-markdown, you must combine this package with
@adobe/mdast-util-gridtables.
Overview
GridTables look like this:
+-------------------+------+
| Table Headings | Here |
+--------+----------+------+
| Sub | Headings | Too |
+========+=================+
| cell | column spanning |
| spans +---------:+------+
| rows | normal | cell |
+---v----+:---------------:+
| | cells can be |
| | *formatted* |
| | **paragraphs** |
| | ``` |
| multi | and contain |
| line | blocks |
| cells | ``` |
+========+=========<+======+
| footer | cells | |
+--------+----------+------+
- the top of a cell must be indicated by
+-followed by some-or+and finished by-+. - if the table contains a footer but no header, the top row should use
=as grid line. - col spans are indicated by missing column (
|) delimiters - row spans are indicated by missing row (
-) delimiters - cells can be left, center, right, or justify aligned; indicated by the placement of
:or>< - cells can be top, middle, or bottom v-aligned; indicated by the placement of arrows (
v^x) - the header and footer sections are delimited by section delimiters (
=). - if no section delimiters are present, all cells are placed in the table body.
- if only 1 section delimiter is present, it delimits header from body.
- the content in cells can be a full Markdown document again. note, that the cell boundaries (
|) need to exactly match with the column markers (+) in the row delimiters, if the cell content contains|, otherwise the correct layout of the table can't be guaranteed.
Layout
The table layout tries to keep the table within a certain width (default 120). For example, if the table has 3 columns, each column will be max 40 characters wide. If all text in a column is smaller, it will shrink the columns. However, cells have a minimum width (default 10) when text needs to be broken. If the cell contents need more space, e.g. with a nested table or code block, it will grow accordingly.
Align
Horizontal align is indicated by placing markers at the grid line above the cell:
Justify Center Left Right
+>-----<+ +:-----:+ +:------+ +------:+
| A b C | | ABC | | ABC | | ABC |
+-------+ +-------+ +-------+ +-------+
Vertical align is indicated by placing markers at the center of the grid line above the cell:
Top Middle Bottom
+---^---+ +---x---+ +---v---+
| Larum | | | | |
| Ipsum | | Larum | | |
| | | Ipsum | | Larum |
| | | | | Ipsum |
+-------+ +-------+ +-------+
Syntax
gridTable := gridLine cellLine+ gridLine;
gridLine := gridCell+ "+";
cellLine := ( gridCell | cellContent )+ ( "+" | "|" );
gridCell := "+" alignMarkerStart? ("-" | "=")+ vAlignMarker? ("-" | "=")* alignMarkerEnd?;
cellContent := ( "+" | "|" ) " " content " " ;
alignMarkerStart := ":" | ">";
alignMarkerEnd := ":" | "<";
vAlignMarker := "^" | "v" | "x"
Usage
Parsing with unified
import { unified } from 'unified';
import remarkParse from 'remark-parse';
import { remarkGridTable } from '@adobe/remark-gridtables';
const mdast = unified()
.use(remarkParse)
.use(remarkGridTable)
.parse(markdown);
Generating HAST
import { toHast, defaultHandlers } from 'mdast-util-to-hast';
import { mdast2hastGridTableHandler, TYPE_TABLE } from '@adobe/helix-markdown-support/gridtable';
const hast = toHast(mdast, {
handlers: {
...defaultHandlers,
[TYPE_TABLE]: mdast2hastGridTableHandler(),
},
allowDangerousHtml: true,
});
Generating HTML
import {micromark} from 'micromark'
import {gridTables, gridTablesHtml} from '@adobe/micromark-extension-gridtables'
const html = micromark(markdown, {
extensions: [gfmTable],
htmlExtensions: [gfmTableHtml]
})
console.log(html)
Installation
$ npm install @adobe/micromark-extension-gridtables
Development
Build
$ npm install
Test
$ npm test
Lint
$ npm run lint