basant307/AI_Governance_Project

1# remark-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**[remark][]** plugin to support [GFM][] (autolink literals, footnotes,12strikethrough, tables, tasklists).13 14## Contents15 16* [What is this?](#what-is-this)17* [When should I use this?](#when-should-i-use-this)18* [Install](#install)19* [Use](#use)20* [API](#api)21  * [`unified().use(remarkGfm[, options])`](#unifieduseremarkgfm-options)22  * [`Options`](#options)23* [Examples](#examples)24  * [Example: `singleTilde`](#example-singletilde)25  * [Example: `stringLength`](#example-stringlength)26* [Bugs](#bugs)27* [Authoring](#authoring)28* [HTML](#html)29* [CSS](#css)30* [Syntax](#syntax)31* [Syntax tree](#syntax-tree)32* [Types](#types)33* [Compatibility](#compatibility)34* [Security](#security)35* [Related](#related)36* [Contribute](#contribute)37* [License](#license)38 39## What is this?40 41This package is a [unified][] ([remark][]) plugin to enable the extensions to42markdown that GitHub adds with GFM: autolink literals (`www.x.com`), footnotes43(`[^1]`), strikethrough (`~~stuff~~`), tables (`| cell |…`), and tasklists44(`* [x]`).45You can use this plugin to add support for parsing and serializing them.46These extensions by GitHub to CommonMark are called [GFM][] (GitHub Flavored47Markdown).48 49This plugin does not handle how markdown is turned to HTML.50That’s done by [`remark-rehype`][remark-rehype].51If your content is not in English and uses footnotes, you should configure that52plugin.53When generating HTML, you might also want to enable [`rehype-slug`][rehype-slug]54to add `id`s on headings.55 56A different plugin, [`remark-frontmatter`][remark-frontmatter], adds support for57frontmatter.58GitHub supports YAML frontmatter for files in repos and Gists but they don’t59treat it as part of GFM.60 61Another plugin, [`remark-github`][remark-github], adds support for how markdown62works in relation to a certain GitHub repo in comments, issues, PRs, and63releases, by linking references to commits, issues, and users.64 65Yet another plugin, [`remark-breaks`][remark-breaks], turns soft line endings66(enters) into hard breaks (`<br>`s).67GitHub does this in a few places (comments, issues, PRs, and releases).68 69## When should I use this?70 71This project is useful when you want to support the same features that GitHub72does in files in a repo, Gists, and several other places.73Users frequently believe that some of these extensions, specifically autolink74literals and tables, are part of normal markdown, so using `remark-gfm` will75help match your implementation to their understanding of markdown.76There are several edge cases where GitHub’s implementation works in unexpected77ways or even different than described in their spec, so *writing* in GFM is not78always the best choice.79 80If you *just* want to turn markdown into HTML (with maybe a few extensions such81as GFM), we recommend [`micromark`][micromark] with82[`micromark-extension-gfm`][micromark-extension-gfm] instead.83If you don’t use plugins and want to access the syntax tree, you can use84[`mdast-util-from-markdown`][mdast-util-from-markdown] with85[`mdast-util-gfm`][mdast-util-gfm].86 87## Install88 89This package is [ESM only][esm].90In Node.js (version 16+), install with [npm][]:91 92```sh93npm install remark-gfm94```95 96In Deno with [`esm.sh`][esmsh]:97 98```js99import remarkGfm from 'https://esm.sh/remark-gfm@4'100```101 102In browsers with [`esm.sh`][esmsh]:103 104```html105<script type="module">106  import remarkGfm from 'https://esm.sh/remark-gfm@4?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` contains:143 144```js145import rehypeStringify from 'rehype-stringify'146import remarkGfm from 'remark-gfm'147import remarkParse from 'remark-parse'148import remarkRehype from 'remark-rehype'149import {read} from 'to-vfile'150import {unified} from 'unified'151 152const file = await unified()153  .use(remarkParse)154  .use(remarkGfm)155  .use(remarkRehype)156  .use(rehypeStringify)157  .process(await read('example.md'))158 159console.log(String(file))160```161 162…then running `node example.js` yields:163 164```html165<h1>GFM</h1>166<h2>Autolink literals</h2>167<p><a href="http://www.example.com">www.example.com</a>, <a href="https://example.com">https://example.com</a>, and <a href="mailto:contact@example.com">contact@example.com</a>.</p>168<h2>Footnote</h2>169<p>A note<sup><a href="#user-content-fn-1" id="user-content-fnref-1" data-footnote-ref aria-describedby="footnote-label">1</a></sup></p>170<h2>Strikethrough</h2>171<p><del>one</del> or <del>two</del> tildes.</p>172<h2>Table</h2>173<table>174<thead>175<tr>176<th>a</th>177<th align="left">b</th>178<th align="right">c</th>179<th align="center">d</th>180</tr>181</thead>182</table>183<h2>Tasklist</h2>184<ul class="contains-task-list">185<li class="task-list-item"><input type="checkbox" disabled> to do</li>186<li class="task-list-item"><input type="checkbox" checked disabled> done</li>187</ul>188<section data-footnotes class="footnotes"><h2 class="sr-only" id="footnote-label">Footnotes</h2>189<ol>190<li id="user-content-fn-1">191<p>Big note. <a href="#user-content-fnref-1" data-footnote-backref class="data-footnote-backref" aria-label="Back to content">↩</a></p>192</li>193</ol>194</section>195```196 197## API198 199This package exports no identifiers.200The default export is [`remarkGfm`][api-remark-gfm].201 202### `unified().use(remarkGfm[, options])`203 204Add support GFM (autolink literals, footnotes, strikethrough, tables,205tasklists).206 207###### Parameters208 209* `options` ([`Options`][api-options], optional)210  — configuration211 212###### Returns213 214Nothing (`undefined`).215 216### `Options`217 218Configuration (TypeScript type).219 220###### Fields221 222* `firstLineBlank` (`boolean`, default: `false`)223  — serialize with a blank line for the first line of footnote definitions224* `stringLength` (`((value: string) => number)`, default: `d => d.length`)225  — detect the size of table cells, used when aligning cells226* `singleTilde` (`boolean`, default: `true`)227  — whether to support strikethrough with a single tilde;228  single tildes work on github.com, but are technically prohibited by GFM;229  you can always use 2 or more tildes for strikethrough230* `tablePipeAlign` (`boolean`, default: `true`)231  — whether to align table pipes232* `tableCellPadding` (`boolean`, default: `true`)233  — whether to add a space of padding between table pipes and cells234 235## Examples236 237### Example: `singleTilde`238 239To turn off support for parsing strikethrough with single tildes, pass240`singleTilde: false`:241 242```js243// …244 245const file = await unified()246  .use(remarkParse)247  .use(remarkGfm, {singleTilde: false})248  .use(remarkRehype)249  .use(rehypeStringify)250  .process('~one~ and ~~two~~')251 252console.log(String(file))253```254 255Yields:256 257```html258<p>~one~ and <del>two</del></p>259```260 261### Example: `stringLength`262 263It’s possible to align tables based on the visual width of cells.264First, let’s show the problem:265 266```js267import {remark} from 'remark'268import remarkGfm from 'remark-gfm'269 270const input = `| Alpha | Bravo |271| - | - |272| 中文 | Charlie |273| 👩‍❤️‍👩 | Delta |`274 275const file = await remark().use(remarkGfm).process(input)276 277console.log(String(file))278```279 280The above code shows how remark can be used to format markdown.281The output is as follows:282 283```markdown284| Alpha    | Bravo   |285| -------- | ------- |286| 中文       | Charlie |287| 👩‍❤️‍👩 | Delta   |288```289 290To improve the alignment of these full-width characters and emoji, pass a291`stringLength` function that calculates the visual width of cells.292One such algorithm is [`string-width`][string-width].293It can be used like so:294 295```diff296@@ -1,5 +1,6 @@297 import {remark} from 'remark'298 import remarkGfm from 'remark-gfm'299+import stringWidth from 'string-width'300 301@@ -10,7 +11,7 @@ async function main() {302 | 👩‍❤️‍👩 | Delta |`303 304-const file = await remark().use(remarkGfm).process(input)305+const file = await remark()306+  .use(remarkGfm, {stringLength: stringWidth})307+  .process(input)308 309   console.log(String(file))310```311 312The output of our code with these changes is as follows:313 314```markdown315| Alpha | Bravo   |316| ----- | ------- |317| 中文  | Charlie |318| 👩‍❤️‍👩    | Delta   |319```320 321## Bugs322 323For bugs present in GFM but not here, or other peculiarities that are324supported, see each corresponding readme:325 326* [autolink literal](https://github.com/micromark/micromark-extension-gfm-autolink-literal#bugs)327* [footnote](https://github.com/micromark/micromark-extension-gfm-footnote#bugs)328* strikethrough: n/a329* [table](https://github.com/micromark/micromark-extension-gfm-table#bugs)330* tasklists: n/a331 332## Authoring333 334For recommendations on how to author GFM, see each corresponding readme:335 336* [autolink literal](https://github.com/micromark/micromark-extension-gfm-autolink-literal#authoring)337* [footnote](https://github.com/micromark/micromark-extension-gfm-footnote#authoring)338* [strikethrough](https://github.com/micromark/micromark-extension-gfm-strikethrough#authoring)339* [table](https://github.com/micromark/micromark-extension-gfm-table#authoring)340* [tasklists](https://github.com/micromark/micromark-extension-gfm-task-list-item#authoring)341 342## HTML343 344This plugin does not handle how markdown is turned to HTML.345See [`remark-rehype`][remark-rehype] for how that happens and how to change it.346 347## CSS348 349For info on how GitHub styles these features, see each corresponding readme:350 351* [autolink literal](https://github.com/micromark/micromark-extension-gfm-autolink-literal#css)352* [footnote](https://github.com/micromark/micromark-extension-gfm-footnote#css)353* [strikethrough](https://github.com/micromark/micromark-extension-gfm-strikethrough#css)354* [table](https://github.com/micromark/micromark-extension-gfm-table#css)355* [tasklists](https://github.com/micromark/micromark-extension-gfm-task-list-item#css)356 357## Syntax358 359For info on the syntax of these features, see each corresponding readme:360 361* [autolink literal](https://github.com/micromark/micromark-extension-gfm-autolink-literal#syntax)362* [footnote](https://github.com/micromark/micromark-extension-gfm-footnote#syntax)363* [strikethrough](https://github.com/micromark/micromark-extension-gfm-strikethrough#syntax)364* [table](https://github.com/micromark/micromark-extension-gfm-table#syntax)365* [tasklists](https://github.com/micromark/micromark-extension-gfm-task-list-item#syntax)366 367## Syntax tree368 369For info on the syntax tree of these features, see each corresponding readme:370 371* [autolink literal](https://github.com/syntax-tree/mdast-util-gfm-autolink-literal#syntax-tree)372* [footnote](https://github.com/syntax-tree/mdast-util-gfm-footnote#syntax-tree)373* [strikethrough](https://github.com/syntax-tree/mdast-util-gfm-strikethrough#syntax-tree)374* [table](https://github.com/syntax-tree/mdast-util-gfm-table#syntax-tree)375* [tasklists](https://github.com/syntax-tree/mdast-util-gfm-task-list-item#syntax-tree)376 377## Types378 379This package is fully typed with [TypeScript][].380It exports the additional type [`Options`][api-options].381 382The node types are supported in `@types/mdast` by default.383 384## Compatibility385 386Projects maintained by the unified collective are compatible with maintained387versions of Node.js.388 389When we cut a new major release, we drop support for unmaintained versions of390Node.391This means we try to keep the current release line, `remark-gfm@^4`, compatible392with Node.js 16.393 394This plugin works with `remark-parse` version 11+ (`remark` version 15+).395The previous version (v3) worked with `remark-parse` version 10 (`remark`396version 14).397Before that, v2 worked with `remark-parse` version 9 (`remark` version 13).398Earlier versions of `remark-parse` and `remark` had a `gfm` option that enabled399this functionality, which defaulted to true.400 401## Security402 403Use of `remark-gfm` does not involve **[rehype][]** ([hast][]) or user404content so there are no openings for [cross-site scripting (XSS)][wiki-xss]405attacks.406 407## Related408 409* [`remark-github`][remark-github]410  — link references to commits, issues, PRs, and users411* [`remark-breaks`][remark-breaks]412  — support breaks without needing spaces or escapes (enters to `<br>`)413* [`remark-frontmatter`][remark-frontmatter]414  — support frontmatter (YAML, TOML, and more)415* [`remark-directive`](https://github.com/remarkjs/remark-directive)416  — support directives417* [`remark-math`](https://github.com/remarkjs/remark-math)418  — support math419* [`remark-mdx`](https://github.com/mdx-js/mdx/tree/main/packages/remark-mdx)420  — support MDX (ESM, JSX, expressions)421 422## Contribute423 424See [`contributing.md`][contributing] in [`remarkjs/.github`][health] for ways425to get started.426See [`support.md`][support] for ways to get help.427 428This project has a [code of conduct][coc].429By interacting with this repository, organization, or community you agree to430abide by its terms.431 432## License433 434[MIT][license] © [Titus Wormer][author]435 436<!-- Definitions -->437 438[api-options]: #options439 440[api-remark-gfm]: #unifieduseremarkgfm-options441 442[author]: https://wooorm.com443 444[backers-badge]: https://opencollective.com/unified/backers/badge.svg445 446[build]: https://github.com/remarkjs/remark-gfm/actions447 448[build-badge]: https://github.com/remarkjs/remark-gfm/workflows/main/badge.svg449 450[chat]: https://github.com/remarkjs/remark/discussions451 452[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg453 454[coc]: https://github.com/remarkjs/.github/blob/HEAD/code-of-conduct.md455 456[collective]: https://opencollective.com/unified457 458[contributing]: https://github.com/remarkjs/.github/blob/HEAD/contributing.md459 460[coverage]: https://codecov.io/github/remarkjs/remark-gfm461 462[coverage-badge]: https://img.shields.io/codecov/c/github/remarkjs/remark-gfm.svg463 464[downloads]: https://www.npmjs.com/package/remark-gfm465 466[downloads-badge]: https://img.shields.io/npm/dm/remark-gfm.svg467 468[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c469 470[esmsh]: https://esm.sh471 472[gfm]: https://github.github.com/gfm/473 474[hast]: https://github.com/syntax-tree/hast475 476[health]: https://github.com/remarkjs/.github477 478[license]: license479 480[mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown481 482[mdast-util-gfm]: https://github.com/syntax-tree/mdast-util-gfm483 484[micromark]: https://github.com/micromark/micromark485 486[micromark-extension-gfm]: https://github.com/micromark/micromark-extension-gfm487 488[npm]: https://docs.npmjs.com/cli/install489 490[rehype]: https://github.com/rehypejs/rehype491 492[rehype-slug]: https://github.com/rehypejs/rehype-slug493 494[remark]: https://github.com/remarkjs/remark495 496[remark-breaks]: https://github.com/remarkjs/remark-breaks497 498[remark-frontmatter]: https://github.com/remarkjs/remark-frontmatter499 500[remark-github]: https://github.com/remarkjs/remark-github501 502[remark-rehype]: https://github.com/remarkjs/remark-rehype503 504[size]: https://bundlejs.com/?q=remark-gfm505 506[size-badge]: https://img.shields.io/bundlejs/size/remark-gfm507 508[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg509 510[string-width]: https://github.com/sindresorhus/string-width511 512[support]: https://github.com/remarkjs/.github/blob/HEAD/support.md513 514[typescript]: https://www.typescriptlang.org515 516[unified]: https://github.com/unifiedjs/unified517 518[wiki-xss]: https://en.wikipedia.org/wiki/Cross-site_scripting519