basant307/AI_Governance_Project

1# mdast-util-gfm-table2 3[![Build][build-badge]][build]4[![Coverage][coverage-badge]][coverage]5[![Downloads][downloads-badge]][downloads]6[![Size][size-badge]][size]7[![Sponsors][sponsors-badge]][collective]8[![Backers][backers-badge]][collective]9[![Chat][chat-badge]][chat]10 11[mdast][] extensions to parse and serialize [GFM][] tables.12 13## Contents14 15*   [What is this?](#what-is-this)16*   [When to use this](#when-to-use-this)17*   [Install](#install)18*   [Use](#use)19*   [API](#api)20    *   [`gfmTableFromMarkdown`](#gfmtablefrommarkdown)21    *   [`gfmTableToMarkdown(options?)`](#gfmtabletomarkdownoptions)22    *   [`Options`](#options)23*   [Examples](#examples)24    *   [Example: `stringLength`](#example-stringlength)25*   [HTML](#html)26*   [Syntax](#syntax)27*   [Syntax tree](#syntax-tree)28    *   [Nodes](#nodes)29    *   [Enumeration](#enumeration)30    *   [Content model](#content-model)31*   [Types](#types)32*   [Compatibility](#compatibility)33*   [Related](#related)34*   [Contribute](#contribute)35*   [License](#license)36 37## What is this?38 39This package contains two extensions that add support for GFM table syntax in40markdown to [mdast][].41These extensions plug into42[`mdast-util-from-markdown`][mdast-util-from-markdown] (to support parsing43tables in markdown into a syntax tree) and44[`mdast-util-to-markdown`][mdast-util-to-markdown] (to support serializing45tables in syntax trees to markdown).46 47## When to use this48 49You can use these extensions when you are working with50`mdast-util-from-markdown` and `mdast-util-to-markdown` already.51 52When working with `mdast-util-from-markdown`, you must combine this package53with [`micromark-extension-gfm-table`][extension].54 55When you don’t need a syntax tree, you can use [`micromark`][micromark]56directly with `micromark-extension-gfm-table`.57 58When you are working with syntax trees and want all of GFM, use59[`mdast-util-gfm`][mdast-util-gfm] instead.60 61All these packages are used [`remark-gfm`][remark-gfm], which62focusses on making it easier to transform content by abstracting these63internals away.64 65This utility does not handle how markdown is turned to HTML.66That’s done by [`mdast-util-to-hast`][mdast-util-to-hast].67 68## Install69 70This package is [ESM only][esm].71In Node.js (version 16+), install with [npm][]:72 73```sh74npm install mdast-util-gfm-table75```76 77In Deno with [`esm.sh`][esmsh]:78 79```js80import {gfmTableFromMarkdown, gfmTableToMarkdown} from 'https://esm.sh/mdast-util-gfm-table@2'81```82 83In browsers with [`esm.sh`][esmsh]:84 85```html86<script type="module">87  import {gfmTableFromMarkdown, gfmTableToMarkdown} from 'https://esm.sh/mdast-util-gfm-table@2?bundle'88</script>89```90 91## Use92 93Say our document `example.md` contains:94 95```markdown96| a | b | c | d |97| - | :- | -: | :-: |98| e | f |99| g | h | i | j | k |100```101 102…and our module `example.js` looks as follows:103 104```js105import fs from 'node:fs/promises'106import {gfmTable} from 'micromark-extension-gfm-table'107import {fromMarkdown} from 'mdast-util-from-markdown'108import {gfmTableFromMarkdown, gfmTableToMarkdown} from 'mdast-util-gfm-table'109import {toMarkdown} from 'mdast-util-to-markdown'110 111const doc = await fs.readFile('example.md')112 113const tree = fromMarkdown(doc, {114  extensions: [gfmTable()],115  mdastExtensions: [gfmTableFromMarkdown()]116})117 118console.log(tree)119 120const out = toMarkdown(tree, {extensions: [gfmTableToMarkdown()]})121 122console.log(out)123```124 125…now running `node example.js` yields (positional info removed for brevity):126 127```js128{129  type: 'root',130  children: [131    {132      type: 'table',133      align: [null, 'left', 'right', 'center'],134      children: [135        {136          type: 'tableRow',137          children: [138            {type: 'tableCell', children: [{type: 'text', value: 'a'}]},139            {type: 'tableCell', children: [{type: 'text', value: 'b'}]},140            {type: 'tableCell', children: [{type: 'text', value: 'c'}]},141            {type: 'tableCell', children: [{type: 'text', value: 'd'}]}142          ]143        },144        {145          type: 'tableRow',146          children: [147            {type: 'tableCell', children: [{type: 'text', value: 'e'}]},148            {type: 'tableCell', children: [{type: 'text', value: 'f'}]}149          ]150        },151        {152          type: 'tableRow',153          children: [154            {type: 'tableCell', children: [{type: 'text', value: 'g'}]},155            {type: 'tableCell', children: [{type: 'text', value: 'h'}]},156            {type: 'tableCell', children: [{type: 'text', value: 'i'}]},157            {type: 'tableCell', children: [{type: 'text', value: 'j'}]},158            {type: 'tableCell', children: [{type: 'text', value: 'k'}]}159          ]160        }161      ]162    }163  ]164}165```166 167```markdown168| a | b  |  c |  d  |   |169| - | :- | -: | :-: | - |170| e | f  |    |     |   |171| g | h  |  i |  j  | k |172```173 174## API175 176This package exports the identifiers177[`gfmTableFromMarkdown`][api-gfm-table-from-markdown] and178[`gfmTableToMarkdown`][api-gfm-table-to-markdown].179There is no default export.180 181### `gfmTableFromMarkdown`182 183Create an extension for [`mdast-util-from-markdown`][mdast-util-from-markdown]184to enable GFM tables in markdown.185 186###### Returns187 188Extension for `mdast-util-from-markdown` to enable GFM tables189([`FromMarkdownExtension`][from-markdown-extension]).190 191### `gfmTableToMarkdown(options?)`192 193Create an extension for [`mdast-util-to-markdown`][mdast-util-to-markdown] to194enable GFM tables in markdown.195 196###### Parameters197 198*   `options` ([`Options`][api-options], optional)199    — configuration200 201###### Returns202 203Extension for `mdast-util-to-markdown` to enable GFM tables204([`ToMarkdownExtension`][to-markdown-extension]).205 206### `Options`207 208Configuration (TypeScript type).209 210###### Fields211 212*   `tableCellPadding` (`boolean`, default: `true`)213    — whether to add a space of padding between delimiters and cells214*   `tablePipeAlign` (`boolean`, default: `true`)215    — whether to align the delimiters216*   `stringLength` (`((value: string) => number)`, default: `s => s.length`)217    — function to detect the length of table cell content, used when aligning218    the delimiters between cells219 220## Examples221 222### Example: `stringLength`223 224It’s possible to align tables based on the visual width of cells.225First, let’s show the problem:226 227```js228import {gfmTable} from 'micromark-extension-gfm-table'229import {fromMarkdown} from 'mdast-util-from-markdown'230import {gfmTableFromMarkdown, gfmTableToMarkdown} from 'mdast-util-gfm-table'231import {toMarkdown} from 'mdast-util-to-markdown'232 233const doc = `| Alpha | Bravo |234| - | - |235| 中文 | Charlie |236| 👩‍❤️‍👩 | Delta |`237 238const tree = fromMarkdown(doc, {239  extensions: [gfmTable],240  mdastExtensions: [gfmTableFromMarkdown]241})242 243console.log(toMarkdown(tree, {extensions: [gfmTableToMarkdown()]}))244```245 246The above code shows how these utilities can be used to format markdown.247The output is as follows:248 249```markdown250| Alpha    | Bravo   |251| -------- | ------- |252| 中文       | Charlie |253| 👩‍❤️‍👩 | Delta   |254```255 256To improve the alignment of these full-width characters and emoji, pass a257`stringLength` function that calculates the visual width of cells.258One such algorithm is [`string-width`][string-width].259It can be used like so:260 261```diff262@@ -2,6 +2,7 @@ import {gfmTable} from 'micromark-extension-gfm-table'263 import {fromMarkdown} from 'mdast-util-from-markdown'264 import {gfmTableFromMarkdown, gfmTableToMarkdown} from 'mdast-util-gfm-table'265 import {toMarkdown} from 'mdast-util-to-markdown'266+import stringWidth from 'string-width'267 268 const doc = `| Alpha | Bravo |269 | - | - |270@@ -13,4 +14,8 @@ const tree = fromMarkdown(doc, {271   mdastExtensions: [gfmTableFromMarkdown()]272 })273 274-console.log(toMarkdown(tree, {extensions: [gfmTableToMarkdown()]}))275+console.log(276+  toMarkdown(tree, {277+    extensions: [gfmTableToMarkdown({stringLength: stringWidth})]278+  })279+)280```281 282The output of our code with these changes is as follows:283 284```markdown285| Alpha | Bravo   |286| ----- | ------- |287| 中文  | Charlie |288| 👩‍❤️‍👩    | Delta   |289```290 291## HTML292 293This utility does not handle how markdown is turned to HTML.294That’s done by [`mdast-util-to-hast`][mdast-util-to-hast].295 296## Syntax297 298See [Syntax in `micromark-extension-gfm-table`][syntax].299 300## Syntax tree301 302The following interfaces are added to **[mdast][]** by this utility.303 304### Nodes305 306#### `Table`307 308```idl309interface Table <: Parent {310  type: 'table'311  align: [alignType]?312  children: [TableContent]313}314```315 316**Table** (**[Parent][dfn-parent]**) represents two-dimensional data.317 318**Table** can be used where **[flow][dfn-flow-content]** content is expected.319Its content model is **[table][dfn-table-content]** content.320 321The *[head][term-head]* of the node represents the labels of the columns.322 323An `align` field can be present.324If present, it must be a list of **[alignTypes][dfn-enum-align-type]**.325It represents how cells in columns are aligned.326 327For example, the following markdown:328 329```markdown330| foo | bar |331| :-- | :-: |332| baz | qux |333```334 335Yields:336 337```js338{339  type: 'table',340  align: ['left', 'center'],341  children: [342    {343      type: 'tableRow',344      children: [345        {346          type: 'tableCell',347          children: [{type: 'text', value: 'foo'}]348        },349        {350          type: 'tableCell',351          children: [{type: 'text', value: 'bar'}]352        }353      ]354    },355    {356      type: 'tableRow',357      children: [358        {359          type: 'tableCell',360          children: [{type: 'text', value: 'baz'}]361        },362        {363          type: 'tableCell',364          children: [{type: 'text', value: 'qux'}]365        }366      ]367    }368  ]369}370```371 372#### `TableRow`373 374```idl375interface TableRow <: Parent {376  type: "tableRow"377  children: [RowContent]378}379```380 381**TableRow** (**[Parent][dfn-parent]**) represents a row of cells in a table.382 383**TableRow** can be used where **[table][dfn-table-content]** content is384expected.385Its content model is **[row][dfn-row-content]** content.386 387If the node is a *[head][term-head]*, it represents the labels of the columns388for its parent **[Table][dfn-table]**.389 390For an example, see **[Table][dfn-table]**.391 392#### `TableCell`393 394```idl395interface TableCell <: Parent {396  type: "tableCell"397  children: [PhrasingContent]398}399```400 401**TableCell** (**[Parent][dfn-parent]**) represents a header cell in a402**[Table][dfn-table]**, if its parent is a *[head][term-head]*, or a data403cell otherwise.404 405**TableCell** can be used where **[row][dfn-row-content]** content is expected.406Its content model is **[phrasing][dfn-phrasing-content]** content excluding407**[Break][dfn-break]** nodes.408 409For an example, see **[Table][dfn-table]**.410 411### Enumeration412 413#### `alignType`414 415```idl416enum alignType {417  'center' | 'left' | 'right' | null418}419```420 421**alignType** represents how phrasing content is aligned422([\[CSSTEXT\]][css-text]).423 424*   **`'left'`**: See the [`left`][css-left] value of the `text-align` CSS425    property426*   **`'right'`**: See the [`right`][css-right] value of the `text-align`427    CSS property428*   **`'center'`**: See the [`center`][css-center] value of the `text-align`429    CSS property430*   **`null`**: phrasing content is aligned as defined by the host environment431 432### Content model433 434#### `FlowContent` (GFM table)435 436```idl437type FlowContentGfm = Table | FlowContent438```439 440#### `TableContent`441 442```idl443type TableContent = TableRow444```445 446**Table** content represent the rows in a table.447 448#### `RowContent`449 450```idl451type RowContent = TableCell452```453 454**Row** content represent the cells in a row.455 456## Types457 458This package is fully typed with [TypeScript][].459It exports the additional type [`Options`][api-options].460 461The `Table`, `TableRow`, and `TableCell` types of the mdast nodes are exposed462from `@types/mdast`.463 464## Compatibility465 466Projects maintained by the unified collective are compatible with maintained467versions of Node.js.468 469When we cut a new major release, we drop support for unmaintained versions of470Node.471This means we try to keep the current release line, `mdast-util-gfm-table@^2`,472compatible with Node.js 16.473 474This utility works with `mdast-util-from-markdown` version 2+ and475`mdast-util-to-markdown` version 2+.476 477## Related478 479*   [`remarkjs/remark-gfm`][remark-gfm]480    — remark plugin to support GFM481*   [`syntax-tree/mdast-util-gfm`][mdast-util-gfm]482    — same but all of GFM (autolink literals, footnotes, strikethrough, tables,483    tasklists)484*   [`micromark/micromark-extension-gfm-table`][extension]485    — micromark extension to parse GFM tables486 487## Contribute488 489See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for490ways to get started.491See [`support.md`][support] for ways to get help.492 493This project has a [code of conduct][coc].494By interacting with this repository, organization, or community you agree to495abide by its terms.496 497## License498 499[MIT][license] © [Titus Wormer][author]500 501<!-- Definitions -->502 503[build-badge]: https://github.com/syntax-tree/mdast-util-gfm-table/workflows/main/badge.svg504 505[build]: https://github.com/syntax-tree/mdast-util-gfm-table/actions506 507[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/mdast-util-gfm-table.svg508 509[coverage]: https://codecov.io/github/syntax-tree/mdast-util-gfm-table510 511[downloads-badge]: https://img.shields.io/npm/dm/mdast-util-gfm-table.svg512 513[downloads]: https://www.npmjs.com/package/mdast-util-gfm-table514 515[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=mdast-util-gfm-table516 517[size]: https://bundlejs.com/?q=mdast-util-gfm-table518 519[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg520 521[backers-badge]: https://opencollective.com/unified/backers/badge.svg522 523[collective]: https://opencollective.com/unified524 525[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg526 527[chat]: https://github.com/syntax-tree/unist/discussions528 529[npm]: https://docs.npmjs.com/cli/install530 531[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c532 533[esmsh]: https://esm.sh534 535[typescript]: https://www.typescriptlang.org536 537[license]: license538 539[author]: https://wooorm.com540 541[health]: https://github.com/syntax-tree/.github542 543[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md544 545[support]: https://github.com/syntax-tree/.github/blob/main/support.md546 547[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md548 549[remark-gfm]: https://github.com/remarkjs/remark-gfm550 551[mdast]: https://github.com/syntax-tree/mdast552 553[mdast-util-gfm]: https://github.com/syntax-tree/mdast-util-gfm554 555[mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown556 557[mdast-util-to-markdown]: https://github.com/syntax-tree/mdast-util-to-markdown558 559[mdast-util-to-hast]: https://github.com/syntax-tree/mdast-util-to-hast560 561[micromark]: https://github.com/micromark/micromark562 563[extension]: https://github.com/micromark/micromark-extension-gfm-table564 565[syntax]: https://github.com/micromark/micromark-extension-gfm-table#syntax566 567[gfm]: https://github.github.com/gfm/568 569[string-width]: https://github.com/sindresorhus/string-width570 571[css-text]: https://drafts.csswg.org/css-text/572 573[css-left]: https://drafts.csswg.org/css-text/#valdef-text-align-left574 575[css-right]: https://drafts.csswg.org/css-text/#valdef-text-align-right576 577[css-center]: https://drafts.csswg.org/css-text/#valdef-text-align-center578 579[term-head]: https://github.com/syntax-tree/unist#head580 581[dfn-parent]: https://github.com/syntax-tree/mdast#parent582 583[dfn-phrasing-content]: https://github.com/syntax-tree/mdast#phrasingcontent584 585[dfn-break]: https://github.com/syntax-tree/mdast#break586 587[from-markdown-extension]: https://github.com/syntax-tree/mdast-util-from-markdown#extension588 589[to-markdown-extension]: https://github.com/syntax-tree/mdast-util-to-markdown#options590 591[api-gfm-table-from-markdown]: #gfmtablefrommarkdown592 593[api-gfm-table-to-markdown]: #gfmtabletomarkdownoptions594 595[api-options]: #options596 597[dfn-flow-content]: #flowcontent-gfm-table598 599[dfn-table-content]: #tablecontent600 601[dfn-enum-align-type]: #aligntype602 603[dfn-row-content]: #rowcontent604 605[dfn-table]: #table606