Awesome
mdast-util-gfm-table
mdast extensions to parse and serialize GFM tables.
Contents
- What is this?
- When to use this
- Install
- Use
- API
- Examples
- HTML
- Syntax
- Syntax tree
- Types
- Compatibility
- Related
- Contribute
- License
What is this?
This package contains two extensions that add support for GFM table syntax in
markdown to mdast.
These extensions plug into
mdast-util-from-markdown
(to support parsing
tables in markdown into a syntax tree) and
mdast-util-to-markdown
(to support serializing
tables in syntax trees to markdown).
When to use this
You can use these extensions when you are working with
mdast-util-from-markdown
and mdast-util-to-markdown
already.
When working with mdast-util-from-markdown
, you must combine this package
with micromark-extension-gfm-table
.
When you don’t need a syntax tree, you can use micromark
directly with micromark-extension-gfm-table
.
When you are working with syntax trees and want all of GFM, use
mdast-util-gfm
instead.
All these packages are used remark-gfm
, which
focusses on making it easier to transform content by abstracting these
internals away.
This utility does not handle how markdown is turned to HTML.
That’s done by mdast-util-to-hast
.
Install
This package is ESM only. In Node.js (version 16+), install with npm:
npm install mdast-util-gfm-table
In Deno with esm.sh
:
import {gfmTableFromMarkdown, gfmTableToMarkdown} from 'https://esm.sh/mdast-util-gfm-table@2'
In browsers with esm.sh
:
<script type="module">
import {gfmTableFromMarkdown, gfmTableToMarkdown} from 'https://esm.sh/mdast-util-gfm-table@2?bundle'
</script>
Use
Say our document example.md
contains:
| a | b | c | d |
| - | :- | -: | :-: |
| e | f |
| g | h | i | j | k |
…and our module example.js
looks as follows:
import fs from 'node:fs/promises'
import {gfmTable} from 'micromark-extension-gfm-table'
import {fromMarkdown} from 'mdast-util-from-markdown'
import {gfmTableFromMarkdown, gfmTableToMarkdown} from 'mdast-util-gfm-table'
import {toMarkdown} from 'mdast-util-to-markdown'
const doc = await fs.readFile('example.md')
const tree = fromMarkdown(doc, {
extensions: [gfmTable()],
mdastExtensions: [gfmTableFromMarkdown()]
})
console.log(tree)
const out = toMarkdown(tree, {extensions: [gfmTableToMarkdown()]})
console.log(out)
…now running node example.js
yields (positional info removed for brevity):
{
type: 'root',
children: [
{
type: 'table',
align: [null, 'left', 'right', 'center'],
children: [
{
type: 'tableRow',
children: [
{type: 'tableCell', children: [{type: 'text', value: 'a'}]},
{type: 'tableCell', children: [{type: 'text', value: 'b'}]},
{type: 'tableCell', children: [{type: 'text', value: 'c'}]},
{type: 'tableCell', children: [{type: 'text', value: 'd'}]}
]
},
{
type: 'tableRow',
children: [
{type: 'tableCell', children: [{type: 'text', value: 'e'}]},
{type: 'tableCell', children: [{type: 'text', value: 'f'}]}
]
},
{
type: 'tableRow',
children: [
{type: 'tableCell', children: [{type: 'text', value: 'g'}]},
{type: 'tableCell', children: [{type: 'text', value: 'h'}]},
{type: 'tableCell', children: [{type: 'text', value: 'i'}]},
{type: 'tableCell', children: [{type: 'text', value: 'j'}]},
{type: 'tableCell', children: [{type: 'text', value: 'k'}]}
]
}
]
}
]
}
| a | b | c | d | |
| - | :- | -: | :-: | - |
| e | f | | | |
| g | h | i | j | k |
API
This package exports the identifiers
gfmTableFromMarkdown
and
gfmTableToMarkdown
.
There is no default export.
gfmTableFromMarkdown
Create an extension for mdast-util-from-markdown
to enable GFM tables in markdown.
Returns
Extension for mdast-util-from-markdown
to enable GFM tables
(FromMarkdownExtension
).
gfmTableToMarkdown(options?)
Create an extension for mdast-util-to-markdown
to
enable GFM tables in markdown.
Parameters
options
(Options
, optional) — configuration
Returns
Extension for mdast-util-to-markdown
to enable GFM tables
(ToMarkdownExtension
).
Options
Configuration (TypeScript type).
Fields
tableCellPadding
(boolean
, default:true
) — whether to add a space of padding between delimiters and cellstablePipeAlign
(boolean
, default:true
) — whether to align the delimitersstringLength
(((value: string) => number)
, default:s => s.length
) — function to detect the length of table cell content, used when aligning the delimiters between cells
Examples
Example: stringLength
It’s possible to align tables based on the visual width of cells. First, let’s show the problem:
import {gfmTable} from 'micromark-extension-gfm-table'
import {fromMarkdown} from 'mdast-util-from-markdown'
import {gfmTableFromMarkdown, gfmTableToMarkdown} from 'mdast-util-gfm-table'
import {toMarkdown} from 'mdast-util-to-markdown'
const doc = `| Alpha | Bravo |
| - | - |
| 中文 | Charlie |
| 👩❤️👩 | Delta |`
const tree = fromMarkdown(doc, {
extensions: [gfmTable],
mdastExtensions: [gfmTableFromMarkdown]
})
console.log(toMarkdown(tree, {extensions: [gfmTableToMarkdown()]}))
The above code shows how these utilities can be used to format markdown. The output is as follows:
| Alpha | Bravo |
| -------- | ------- |
| 中文 | Charlie |
| 👩❤️👩 | Delta |
To improve the alignment of these full-width characters and emoji, pass a
stringLength
function that calculates the visual width of cells.
One such algorithm is string-width
.
It can be used like so:
@@ -2,6 +2,7 @@ import {gfmTable} from 'micromark-extension-gfm-table'
import {fromMarkdown} from 'mdast-util-from-markdown'
import {gfmTableFromMarkdown, gfmTableToMarkdown} from 'mdast-util-gfm-table'
import {toMarkdown} from 'mdast-util-to-markdown'
+import stringWidth from 'string-width'
const doc = `| Alpha | Bravo |
| - | - |
@@ -13,4 +14,8 @@ const tree = fromMarkdown(doc, {
mdastExtensions: [gfmTableFromMarkdown()]
})
-console.log(toMarkdown(tree, {extensions: [gfmTableToMarkdown()]}))
+console.log(
+ toMarkdown(tree, {
+ extensions: [gfmTableToMarkdown({stringLength: stringWidth})]
+ })
+)
The output of our code with these changes is as follows:
| Alpha | Bravo |
| ----- | ------- |
| 中文 | Charlie |
| 👩❤️👩 | Delta |
HTML
This utility does not handle how markdown is turned to HTML.
That’s done by mdast-util-to-hast
.
Syntax
See Syntax in micromark-extension-gfm-table
.
Syntax tree
The following interfaces are added to mdast by this utility.
Nodes
Table
interface Table <: Parent {
type: 'table'
align: [alignType]?
children: [TableContent]
}
Table (Parent) represents two-dimensional data.
Table can be used where flow content is expected. Its content model is table content.
The head of the node represents the labels of the columns.
An align
field can be present.
If present, it must be a list of alignTypes.
It represents how cells in columns are aligned.
For example, the following markdown:
| foo | bar |
| :-- | :-: |
| baz | qux |
Yields:
{
type: 'table',
align: ['left', 'center'],
children: [
{
type: 'tableRow',
children: [
{
type: 'tableCell',
children: [{type: 'text', value: 'foo'}]
},
{
type: 'tableCell',
children: [{type: 'text', value: 'bar'}]
}
]
},
{
type: 'tableRow',
children: [
{
type: 'tableCell',
children: [{type: 'text', value: 'baz'}]
},
{
type: 'tableCell',
children: [{type: 'text', value: 'qux'}]
}
]
}
]
}
TableRow
interface TableRow <: Parent {
type: "tableRow"
children: [RowContent]
}
TableRow (Parent) represents a row of cells in a table.
TableRow can be used where table content is expected. Its content model is row content.
If the node is a head, it represents the labels of the columns for its parent Table.
For an example, see Table.
TableCell
interface TableCell <: Parent {
type: "tableCell"
children: [PhrasingContent]
}
TableCell (Parent) represents a header cell in a Table, if its parent is a head, or a data cell otherwise.
TableCell can be used where row content is expected. Its content model is phrasing content excluding Break nodes.
For an example, see Table.
Enumeration
alignType
enum alignType {
'center' | 'left' | 'right' | null
}
alignType represents how phrasing content is aligned ([CSSTEXT]).
'left'
: See theleft
value of thetext-align
CSS property'right'
: See theright
value of thetext-align
CSS property'center'
: See thecenter
value of thetext-align
CSS propertynull
: phrasing content is aligned as defined by the host environment
Content model
FlowContent
(GFM table)
type FlowContentGfm = Table | FlowContent
TableContent
type TableContent = TableRow
Table content represent the rows in a table.
RowContent
type RowContent = TableCell
Row content represent the cells in a row.
Types
This package is fully typed with TypeScript.
It exports the additional type Options
.
The Table
, TableRow
, and TableCell
types of the mdast nodes are exposed
from @types/mdast
.
Compatibility
Projects maintained by the unified collective are compatible with maintained versions of Node.js.
When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, mdast-util-gfm-table@^2
,
compatible with Node.js 16.
This utility works with mdast-util-from-markdown
version 2+ and
mdast-util-to-markdown
version 2+.
Related
remarkjs/remark-gfm
— remark plugin to support GFMsyntax-tree/mdast-util-gfm
— same but all of GFM (autolink literals, footnotes, strikethrough, tables, tasklists)micromark/micromark-extension-gfm-table
— micromark extension to parse GFM tables
Contribute
See contributing.md
in syntax-tree/.github
for
ways to get started.
See support.md
for ways to get help.
This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.