basant307/AI_Governance_Project

1# mdast-util-gfm2 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][] (autolink literals,12footnotes, strikethrough, tables, tasklists).13 14## Contents15 16* [What is this?](#what-is-this)17* [When to use this](#when-to-use-this)18* [Install](#install)19* [Use](#use)20* [API](#api)21  * [`gfmFromMarkdown()`](#gfmfrommarkdown)22  * [`gfmToMarkdown(options?)`](#gfmtomarkdownoptions)23  * [`Options`](#options)24* [HTML](#html)25* [Syntax](#syntax)26* [Syntax tree](#syntax-tree)27* [Types](#types)28* [Compatibility](#compatibility)29* [Related](#related)30* [Contribute](#contribute)31* [License](#license)32 33## What is this?34 35This package contains two extensions that add support for GFM syntax in36markdown to [mdast][]: autolink literals (`www.x.com`), footnotes (`[^1]`),37strikethrough (`~~stuff~~`), tables (`| cell |…`), and tasklists (`* [x]`).38These extensions plug into39[`mdast-util-from-markdown`][mdast-util-from-markdown] (to support parsing40GFM in markdown into a syntax tree) and41[`mdast-util-to-markdown`][mdast-util-to-markdown] (to support serializing42GFM in syntax trees to markdown).43 44## When to use this45 46This project is useful when you want to support the same features that GitHub47does in files in a repo, Gists, and several other places.48Users frequently believe that some of these extensions, specifically autolink49literals and tables, are part of normal markdown, so using `mdast-util-gfm` will50help match your implementation to their understanding of markdown.51There are several edge cases where GitHub’s implementation works in unexpected52ways or even different than described in their spec, so *writing* in GFM is not53always the best choice.54 55You can use these extensions when you are working with56`mdast-util-from-markdown` and `mdast-util-to-markdown` already.57 58When working with `mdast-util-from-markdown`, you must combine this package59with [`micromark-extension-gfm`][extension].60 61Instead of this package, you can also use the extensions separately:62 63* [`mdast-util-gfm-autolink-literal`](https://github.com/syntax-tree/mdast-util-gfm-autolink-literal)64  — support GFM autolink literals65* [`mdast-util-gfm-footnote`](https://github.com/syntax-tree/mdast-util-gfm-footnote)66  — support GFM footnotes67* [`mdast-util-gfm-strikethrough`](https://github.com/syntax-tree/mdast-util-gfm-strikethrough)68  — support GFM strikethrough69* [`mdast-util-gfm-table`](https://github.com/syntax-tree/mdast-util-gfm-table)70  — support GFM tables71* [`mdast-util-gfm-task-list-item`](https://github.com/syntax-tree/mdast-util-gfm-task-list-item)72  — support GFM tasklists73 74A different utility, [`mdast-util-frontmatter`][mdast-util-frontmatter], adds75support for frontmatter.76GitHub supports YAML frontmatter for files in repos and Gists but they don’t77treat it as part of GFM.78 79All these packages are used in [`remark-gfm`][remark-gfm], which80focusses on making it easier to transform content by abstracting these81internals away.82 83This utility does not handle how markdown is turned to HTML.84That’s done by [`mdast-util-to-hast`][mdast-util-to-hast].85If your content is not in English, you should configure that utility.86 87## Install88 89This package is [ESM only][esm].90In Node.js (version 16+), install with [npm][]:91 92```sh93npm install mdast-util-gfm94```95 96In Deno with [`esm.sh`][esmsh]:97 98```js99import {gfmFromMarkdown, gfmToMarkdown} from 'https://esm.sh/mdast-util-gfm@3'100```101 102In browsers with [`esm.sh`][esmsh]:103 104```html105<script type="module">106  import {gfmFromMarkdown, gfmToMarkdown} from 'https://esm.sh/mdast-util-gfm@3?bundle'107</script>108```109 110## Use111 112Say our document `example.md` contains:113 114```markdown115# GFM116 117## Autolink literals118 119www.example.com, https://example.com, and contact@example.com.120 121## Footnote122 123A note[^1]124 125[^1]: Big note.126 127## Strikethrough128 129~one~ or ~~two~~ tildes.130 131## Table132 133| a | b  |  c |  d  |134| - | :- | -: | :-: |135 136## Tasklist137 138* [ ] to do139* [x] done140```141 142…and our module `example.js` looks as follows:143 144```js145import fs from 'node:fs/promises'146import {fromMarkdown} from 'mdast-util-from-markdown'147import {gfmFromMarkdown, gfmToMarkdown} from 'mdast-util-gfm'148import {toMarkdown} from 'mdast-util-to-markdown'149import {gfm} from 'micromark-extension-gfm'150 151const value = await fs.readFile('example.md', 'utf8')152 153const tree = fromMarkdown(value, {154  extensions: [gfm()],155  mdastExtensions: [gfmFromMarkdown()]156})157 158console.log(tree)159 160const result = toMarkdown(tree, {extensions: [gfmToMarkdown()]})161 162console.log(result)163```164 165…now running `node example.js` yields (positional info removed for brevity):166 167```js168{169  type: 'root',170  children: [171    {type: 'heading', depth: 1, children: [{type: 'text', value: 'GFM'}]},172    {173      type: 'heading',174      depth: 2,175      children: [{type: 'text', value: 'Autolink literals'}]176    },177    {178      type: 'paragraph',179      children: [180        {181          type: 'link',182          title: null,183          url: 'http://www.example.com',184          children: [{type: 'text', value: 'www.example.com'}]185        },186        {type: 'text', value: ', '},187        {188          type: 'link',189          title: null,190          url: 'https://example.com',191          children: [{type: 'text', value: 'https://example.com'}]192        },193        {type: 'text', value: ', and '},194        {195          type: 'link',196          title: null,197          url: 'mailto:contact@example.com',198          children: [{type: 'text', value: 'contact@example.com'}]199        },200        {type: 'text', value: '.'}201      ]202    },203    {type: 'heading', depth: 2, children: [{type: 'text', value: 'Footnote'}]},204    {205      type: 'paragraph',206      children: [207        {type: 'text', value: 'A note'},208        {type: 'footnoteReference', identifier: '1', label: '1'}209      ]210    },211    {212      type: 'footnoteDefinition',213      identifier: '1',214      label: '1',215      children: [216        {type: 'paragraph', children: [{type: 'text', value: 'Big note.'}]}217      ]218    },219    {220      type: 'heading',221      depth: 2,222      children: [{type: 'text', value: 'Strikethrough'}]223    },224    {225      type: 'paragraph',226      children: [227        {228          type: 'delete',229          children: [{type: 'text', value: 'one'}]230        },231        {type: 'text', value: ' or '},232        {233          type: 'delete',234          children: [{type: 'text', value: 'two'}]235        },236        {type: 'text', value: ' tildes.'}237      ]238    },239    {type: 'heading', depth: 2, children: [{type: 'text', value: 'Table'}]},240    {241      type: 'table',242      align: [null, 'left', 'right', 'center'],243      children: [244        {245          type: 'tableRow',246          children: [247            {type: 'tableCell', children: [{type: 'text', value: 'a'}]},248            {type: 'tableCell', children: [{type: 'text', value: 'b'}]},249            {type: 'tableCell', children: [{type: 'text', value: 'c'}]},250            {type: 'tableCell', children: [{type: 'text', value: 'd'}]}251          ]252        }253      ]254    },255    {type: 'heading', depth: 2, children: [{type: 'text', value: 'Tasklist'}]},256    {257      type: 'list',258      ordered: false,259      start: null,260      spread: false,261      children: [262        {263          type: 'listItem',264          spread: false,265          checked: false,266          children: [267            {type: 'paragraph', children: [{type: 'text', value: 'to do'}]}268          ]269        },270        {271          type: 'listItem',272          spread: false,273          checked: true,274          children: [275            {type: 'paragraph', children: [{type: 'text', value: 'done'}]}276          ]277        }278      ]279    }280  ]281}282```283 284```markdown285# GFM286 287## Autolink literals288 289[www.example.com](http://www.example.com), <https://example.com>, and <contact@example.com>.290 291## Footnote292 293A note[^1]294 295[^1]: Big note.296 297## Strikethrough298 299~~one~~ or ~~two~~ tildes.300 301## Table302 303| a | b  |  c |  d  |304| - | :- | -: | :-: |305 306## Tasklist307 308*   [ ] to do309*   [x] done310```311 312## API313 314This package exports the identifiers [`gfmFromMarkdown`][api-gfm-from-markdown]315and [`gfmToMarkdown`][api-gfm-to-markdown].316There is no default export.317 318### `gfmFromMarkdown()`319 320Create an extension for [`mdast-util-from-markdown`][mdast-util-from-markdown]321to enable GFM (autolink literals, footnotes, strikethrough, tables, tasklists).322 323###### Returns324 325Extension for `mdast-util-from-markdown` to enable GFM326([`Array<FromMarkdownExtension>`][from-markdown-extension]).327 328### `gfmToMarkdown(options?)`329 330Create an extension for [`mdast-util-to-markdown`][mdast-util-to-markdown]331to enable GFM (autolink literals, footnotes, strikethrough, tables, tasklists).332 333###### Parameters334 335* `options` ([`Options`][api-options])336  — configuration337 338###### Returns339 340Extension for `mdast-util-to-markdown` to enable GFM341([`Array<ToMarkdownExtension>`][to-markdown-extension]).342 343### `Options`344 345Configuration (TypeScript type).346 347###### Fields348 349* `firstLineBlank` (`boolean`, default: `false`)350  — use a blank line for the first line of footnote definitions351* `stringLength` (`((value: string) => number)`, default: `s => s.length`)352  — function to detect the length of table cell content, used when aligning353  the delimiters between cells354* `tableCellPadding` (`boolean`, default: `true`)355  — whether to add a space of padding between delimiters and cells356* `tablePipeAlign` (`boolean`, default: `true`)357  — whether to align the delimiters358 359## HTML360 361This utility does not handle how markdown is turned to HTML.362That’s done by [`mdast-util-to-hast`][mdast-util-to-hast].363 364## Syntax365 366See [Syntax in `micromark-extension-gfm`][syntax].367 368## Syntax tree369 370This utility combines several mdast utilities.371See their readmes for the node types supported in the tree:372 373* [`mdast-util-gfm-autolink-literal`](https://github.com/syntax-tree/mdast-util-gfm-autolink-literal#syntax-tree)374  — GFM autolink literals375* [`mdast-util-gfm-footnote`](https://github.com/syntax-tree/mdast-util-gfm-footnote#syntax-tree)376  — GFM footnotes377* [`mdast-util-gfm-strikethrough`](https://github.com/syntax-tree/mdast-util-gfm-strikethrough#syntax-tree)378  — GFM strikethrough379* [`mdast-util-gfm-table`](https://github.com/syntax-tree/mdast-util-gfm-table#syntax-tree)380  — GFM tables381* [`mdast-util-gfm-task-list-item`](https://github.com/syntax-tree/mdast-util-gfm-task-list-item#syntax-tree)382  — GFM tasklists383 384## Types385 386This package is fully typed with [TypeScript][].387It exports the additional type [`Options`][api-options].388 389The `Delete`, `FootnoteDefinition`, `FootnoteReference`, `Table`, `TableRow`,390and `TableCell` types of the mdast nodes are exposed from `@types/mdast`.391 392## Compatibility393 394Projects maintained by the unified collective are compatible with maintained395versions of Node.js.396 397When we cut a new major release, we drop support for unmaintained versions of398Node.399This means we try to keep the current release line, `mdast-util-gfm@^3`,400compatible with Node.js 16.401 402## Related403 404* [`remark-gfm`][remark-gfm]405  — remark plugin to support GFM406* [`micromark-extension-gfm`][extension]407  — micromark extension to parse GFM408 409## Contribute410 411See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for412ways to get started.413See [`support.md`][support] for ways to get help.414 415This project has a [code of conduct][coc].416By interacting with this repository, organization, or community you agree to417abide by its terms.418 419## License420 421[MIT][license] © [Titus Wormer][author]422 423<!-- Definitions -->424 425[api-gfm-from-markdown]: #gfmfrommarkdown426 427[api-gfm-to-markdown]: #gfmtomarkdownoptions428 429[api-options]: #options430 431[author]: https://wooorm.com432 433[backers-badge]: https://opencollective.com/unified/backers/badge.svg434 435[build]: https://github.com/syntax-tree/mdast-util-gfm/actions436 437[build-badge]: https://github.com/syntax-tree/mdast-util-gfm/workflows/main/badge.svg438 439[chat]: https://github.com/syntax-tree/unist/discussions440 441[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg442 443[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md444 445[collective]: https://opencollective.com/unified446 447[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md448 449[coverage]: https://codecov.io/github/syntax-tree/mdast-util-gfm450 451[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/mdast-util-gfm.svg452 453[downloads]: https://www.npmjs.com/package/mdast-util-gfm454 455[downloads-badge]: https://img.shields.io/npm/dm/mdast-util-gfm.svg456 457[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c458 459[esmsh]: https://esm.sh460 461[extension]: https://github.com/micromark/micromark-extension-gfm462 463[from-markdown-extension]: https://github.com/syntax-tree/mdast-util-from-markdown#extension464 465[gfm]: https://github.github.com/gfm/466 467[health]: https://github.com/syntax-tree/.github468 469[license]: license470 471[mdast]: https://github.com/syntax-tree/mdast472 473[mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown474 475[mdast-util-frontmatter]: https://github.com/syntax-tree/mdast-util-frontmatter476 477[mdast-util-to-hast]: https://github.com/syntax-tree/mdast-util-to-hast478 479[mdast-util-to-markdown]: https://github.com/syntax-tree/mdast-util-to-markdown480 481[npm]: https://docs.npmjs.com/cli/install482 483[remark-gfm]: https://github.com/remarkjs/remark-gfm484 485[size]: https://bundlejs.com/?q=mdast-util-gfm486 487[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=mdast-util-gfm488 489[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg490 491[support]: https://github.com/syntax-tree/.github/blob/main/support.md492 493[syntax]: https://github.com/micromark/micromark-extension-gfm#syntax494 495[to-markdown-extension]: https://github.com/syntax-tree/mdast-util-to-markdown#options496 497[typescript]: https://www.typescriptlang.org498