weseek__growi/packages/micromark-extension-gfm-table

micromark-extension-gfm-table

micromark extension to support GFM tables.

Contents

• What is this?
• When to use this
• Install
• Use
• API
  • gfmTable
  • gfmTableHtml
• Authoring
• HTML
• CSS
• Syntax
• Types
• Compatibility
• Security
• Related
• Contribute
• License

What is this?

This package contains extensions that add support for tables enabled by GFM to micromark. It matches how tables work on github.com.

When to use this

These tools are all low-level. In many cases, you want to use remark-gfm with remark instead.

Even when you want to use micromark, you likely want to use micromark-extension-gfm to support all GFM features. That extension includes this extension.

When working with mdast-util-from-markdown, you must combine this package with mdast-util-gfm-table.

Install

This package is ESM only. In Node.js (version 12.20+, 14.14+, 16.0+, or 18.0+), install with npm:

npm install micromark-extension-gfm-table

In Deno with esm.sh:

import {gfmTable, gfmTableHtml} from 'https://esm.sh/micromark-extension-gfm-table@1'

In browsers with esm.sh:

<script type="module">
  import {gfmTable, gfmTableHtml} from 'https://esm.sh/micromark-extension-gfm-table@1?bundle'
</script>

Use

import {micromark} from 'micromark'
import {gfmTable, gfmTableHtml} from 'micromark-extension-gfm-table'

const output = micromark('| a |\n| - |', {
  extensions: [gfmTable],
  htmlExtensions: [gfmTableHtml]
})

console.log(output)

Yields:

<table>
<thead>
<tr>
<th>a</th>
</tr>
</thead>
</table>

API

This package exports the identifiers gfmTable and gfmTableHtml. There is no default export.

The export map supports the endorsed development condition. Run node --conditions development module.js to get instrumented dev code. Without this condition, production code is loaded.

gfmTable

Syntax extension for micromark (passed in extensions).

gfmTableHtml

HTML extension for micromark (passed in htmlExtensions).

Authoring

Align

When authoring markdown with tables, it can get a bit hard to make them look well. You can align the pipes (|) in rows nicely, which makes it easier to spot problems, but aligning gets cumbersome for tables with many rows or columns, or when they change frequently, especially if data in cells have varying lengths. To illustrate, when some cell increases in size which makes it longer than all other cells in that column, you’d have to pad every other cell as well, which can be a lot of work, and will introduce a giant diff in Git.

Initial and final pipes

In some cases, GFM tables can be written without initial or final pipes:

name  | letter
----- | ------
alpha | a
bravo | b

These tables do not parse in certain other cases, making them fragile and hard to get right. Due to this, it’s recommended to always include initial and final pipes.

Escaped pipes in code

GitHub applies one weird, special thing in tables that markdown otherwise never does: it allows character escapes (not character references) of pipes (not other characters) in code in cells. It’s weird, because markdown, per CommonMark, does not allow character escapes in code. GitHub only applies this change in code in tables:

| `a\|b\-` |
| - |

`a\|b\-`

Yields:

<table>
<thead>
<tr>
<th><code>a|b\-</code></th>
</tr>
</thead>
</table>
<p><code>a\|b\-</code></p>

👉 Note: observe that the escaped pipe in the table does not result in another column, and is not present in the resulting code. Other escapes, and pipe escapes outside tables, do nothing.

This behavior solves a real problem, so you might resort to using it. It might not work in other markdown parsers though.

HTML

GFM tables relate to several tabular data HTML elements: See § 4.9.1 The table element, § 4.9.5 The tbody element, § 4.9.6 The thead element, § 4.9.8 The tr element, § 4.9.9 The td element, and § 4.9.10 The th element in the HTML spec for more info.

GitHub provides the alignment information from the delimiter row on each <td> and <th> element with an align attribute. This feature stems from ancient times in HTML, and still works, but is considered a non-conforming feature, which must not be used by authors.

CSS

The following CSS is needed to make tables look a bit like GitHub. For the complete actual CSS see sindresorhus/github-markdown-css

/* Light theme. */
:root {
  --color-canvas-default: #ffffff;
  --color-canvas-subtle: #f6f8fa;
  --color-border-default: #d0d7de;
  --color-border-muted: hsla(210, 18%, 87%, 1);
}

/* Dark theme. */
@media (prefers-color-scheme: dark) {
  :root {
    --color-canvas-default: #0d1117;
    --color-canvas-subtle: #161b22;
    --color-border-default: #30363d;
    --color-border-muted: #21262d;
  }
}

table {
  border-spacing: 0;
  border-collapse: collapse;
  display: block;
  margin-top: 0;
  margin-bottom: 16px;
  width: max-content;
  max-width: 100%;
  overflow: auto;
}

tr {
  background-color: var(--color-canvas-default);
  border-top: 1px solid var(--color-border-muted);
}

tr:nth-child(2n) {
  background-color: var(--color-canvas-subtle);
}

td,
th {
  padding: 6px 13px;
  border: 1px solid var(--color-border-default);
}

th {
  font-weight: 600;
}

table img {
  background-color: transparent;
}

Syntax

Tables form with, roughly, the following BNF:

; Restriction: number of cells in first row must match number of cells in delimiter row.
table ::= row eol delimiter_row 0.*( eol row )

; Restriction: Line cannot be blank.
row ::= [ '|' ] cell 0.*( '|' cell ) [ '|' ]
delimiter_row ::= [ '|' ] delimiter_cell 0.*( '|' delimiter_cell ) [ '|' ]

cell ::= 0.*space_or_tab 0.*( cell_text | cell_escape ) 0.*space_or_tab
cell_text ::= code - eol - '|' - '\\' - ''
cell_escape ::= '\\' ( '|' | '\\' )
delimiter_cell ::= 0.*space_or_tab [ ':' ] 1*'-' [ ':' ] 0.*space_or_tab

Types

This package is fully typed with TypeScript. There are no additional exported types.

Compatibility

This package is at least compatible with all maintained versions of Node.js. As of now, that is Node.js 12.20+, 14.14+, 16.0+, and 18.0+. It also works in Deno and modern browsers.

Security

This package is safe.

Related

• syntax-tree/mdast-util-gfm-table — support GFM tables in mdast
• syntax-tree/mdast-util-gfm — support GFM in mdast
• remarkjs/remark-gfm — support GFM in remark

Contribute

See contributing.md in micromark/.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.

License

MIT © Titus Wormer