{"id":13339491,"url":"https://github.com/syntax-tree/mdast-util-gfm","last_synced_at":"2025-06-29T22:03:52.271Z","repository":{"id":43173204,"uuid":"296709284","full_name":"syntax-tree/mdast-util-gfm","owner":"syntax-tree","description":"mdast extension to parse and serialize GFM (GitHub Flavored Markdown)","archived":false,"fork":false,"pushed_at":"2025-02-10T12:33:49.000Z","size":119,"stargazers_count":19,"open_issues_count":0,"forks_count":7,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-05-19T10:21:21.880Z","etag":null,"topics":["autolink","gfm","github","markdown","mdast","mdast-util","strikethrough","table","tasklist","unist"],"latest_commit_sha":null,"homepage":"https://unifiedjs.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/syntax-tree.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"license","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"unifiedjs","open_collective":"unified"}},"created_at":"2020-09-18T19:12:47.000Z","updated_at":"2025-03-24T01:48:38.000Z","dependencies_parsed_at":"2024-06-18T15:18:09.949Z","dependency_job_id":"56bd407f-90cb-407b-b49c-cbb1a1010836","html_url":"https://github.com/syntax-tree/mdast-util-gfm","commit_stats":{"total_commits":64,"total_committers":2,"mean_commits":32.0,"dds":0.015625,"last_synced_commit":"6e651ee023a285359f9bd0c1427121e4a0d43cdb"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/syntax-tree/mdast-util-gfm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syntax-tree%2Fmdast-util-gfm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syntax-tree%2Fmdast-util-gfm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syntax-tree%2Fmdast-util-gfm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syntax-tree%2Fmdast-util-gfm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/syntax-tree","download_url":"https://codeload.github.com/syntax-tree/mdast-util-gfm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syntax-tree%2Fmdast-util-gfm/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261200179,"owners_count":23123925,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["autolink","gfm","github","markdown","mdast","mdast-util","strikethrough","table","tasklist","unist"],"created_at":"2024-07-29T19:20:04.084Z","updated_at":"2025-06-29T22:03:52.227Z","avatar_url":"https://github.com/syntax-tree.png","language":"JavaScript","funding_links":["https://github.com/sponsors/unifiedjs","https://opencollective.com/unified"],"categories":[],"sub_categories":[],"readme":"# mdast-util-gfm\n\n[![Build][build-badge]][build]\n[![Coverage][coverage-badge]][coverage]\n[![Downloads][downloads-badge]][downloads]\n[![Size][size-badge]][size]\n[![Sponsors][sponsors-badge]][collective]\n[![Backers][backers-badge]][collective]\n[![Chat][chat-badge]][chat]\n\n[mdast][] extensions to parse and serialize [GFM][] (autolink literals,\nfootnotes, strikethrough, tables, tasklists).\n\n## Contents\n\n* [What is this?](#what-is-this)\n* [When to use this](#when-to-use-this)\n* [Install](#install)\n* [Use](#use)\n* [API](#api)\n  * [`gfmFromMarkdown()`](#gfmfrommarkdown)\n  * [`gfmToMarkdown(options?)`](#gfmtomarkdownoptions)\n  * [`Options`](#options)\n* [HTML](#html)\n* [Syntax](#syntax)\n* [Syntax tree](#syntax-tree)\n* [Types](#types)\n* [Compatibility](#compatibility)\n* [Related](#related)\n* [Contribute](#contribute)\n* [License](#license)\n\n## What is this?\n\nThis package contains two extensions that add support for GFM syntax in\nmarkdown to [mdast][]: autolink literals (`www.x.com`), footnotes (`[^1]`),\nstrikethrough (`~~stuff~~`), tables (`| cell |…`), and tasklists (`* [x]`).\nThese extensions plug into\n[`mdast-util-from-markdown`][mdast-util-from-markdown] (to support parsing\nGFM in markdown into a syntax tree) and\n[`mdast-util-to-markdown`][mdast-util-to-markdown] (to support serializing\nGFM in syntax trees to markdown).\n\n## When to use this\n\nThis project is useful when you want to support the same features that GitHub\ndoes in files in a repo, Gists, and several other places.\nUsers frequently believe that some of these extensions, specifically autolink\nliterals and tables, are part of normal markdown, so using `mdast-util-gfm` will\nhelp match your implementation to their understanding of markdown.\nThere are several edge cases where GitHub’s implementation works in unexpected\nways or even different than described in their spec, so *writing* in GFM is not\nalways the best choice.\n\nYou can use these extensions when you are working with\n`mdast-util-from-markdown` and `mdast-util-to-markdown` already.\n\nWhen working with `mdast-util-from-markdown`, you must combine this package\nwith [`micromark-extension-gfm`][extension].\n\nInstead of this package, you can also use the extensions separately:\n\n* [`mdast-util-gfm-autolink-literal`](https://github.com/syntax-tree/mdast-util-gfm-autolink-literal)\n  — support GFM autolink literals\n* [`mdast-util-gfm-footnote`](https://github.com/syntax-tree/mdast-util-gfm-footnote)\n  — support GFM footnotes\n* [`mdast-util-gfm-strikethrough`](https://github.com/syntax-tree/mdast-util-gfm-strikethrough)\n  — support GFM strikethrough\n* [`mdast-util-gfm-table`](https://github.com/syntax-tree/mdast-util-gfm-table)\n  — support GFM tables\n* [`mdast-util-gfm-task-list-item`](https://github.com/syntax-tree/mdast-util-gfm-task-list-item)\n  — support GFM tasklists\n\nA different utility, [`mdast-util-frontmatter`][mdast-util-frontmatter], adds\nsupport for frontmatter.\nGitHub supports YAML frontmatter for files in repos and Gists but they don’t\ntreat it as part of GFM.\n\nAll these packages are used in [`remark-gfm`][remark-gfm], which\nfocusses on making it easier to transform content by abstracting these\ninternals away.\n\nThis utility does not handle how markdown is turned to HTML.\nThat’s done by [`mdast-util-to-hast`][mdast-util-to-hast].\nIf your content is not in English, you should configure that utility.\n\n## Install\n\nThis package is [ESM only][esm].\nIn Node.js (version 16+), install with [npm][]:\n\n```sh\nnpm install mdast-util-gfm\n```\n\nIn Deno with [`esm.sh`][esmsh]:\n\n```js\nimport {gfmFromMarkdown, gfmToMarkdown} from 'https://esm.sh/mdast-util-gfm@3'\n```\n\nIn browsers with [`esm.sh`][esmsh]:\n\n```html\n\u003cscript type=\"module\"\u003e\n  import {gfmFromMarkdown, gfmToMarkdown} from 'https://esm.sh/mdast-util-gfm@3?bundle'\n\u003c/script\u003e\n```\n\n## Use\n\nSay our document `example.md` contains:\n\n```markdown\n# GFM\n\n## Autolink literals\n\nwww.example.com, https://example.com, and contact@example.com.\n\n## Footnote\n\nA note[^1]\n\n[^1]: Big note.\n\n## Strikethrough\n\n~one~ or ~~two~~ tildes.\n\n## Table\n\n| a | b  |  c |  d  |\n| - | :- | -: | :-: |\n\n## Tasklist\n\n* [ ] to do\n* [x] done\n```\n\n…and our module `example.js` looks as follows:\n\n```js\nimport fs from 'node:fs/promises'\nimport {fromMarkdown} from 'mdast-util-from-markdown'\nimport {gfmFromMarkdown, gfmToMarkdown} from 'mdast-util-gfm'\nimport {toMarkdown} from 'mdast-util-to-markdown'\nimport {gfm} from 'micromark-extension-gfm'\n\nconst value = await fs.readFile('example.md', 'utf8')\n\nconst tree = fromMarkdown(value, {\n  extensions: [gfm()],\n  mdastExtensions: [gfmFromMarkdown()]\n})\n\nconsole.log(tree)\n\nconst result = toMarkdown(tree, {extensions: [gfmToMarkdown()]})\n\nconsole.log(result)\n```\n\n…now running `node example.js` yields (positional info removed for brevity):\n\n```js\n{\n  type: 'root',\n  children: [\n    {type: 'heading', depth: 1, children: [{type: 'text', value: 'GFM'}]},\n    {\n      type: 'heading',\n      depth: 2,\n      children: [{type: 'text', value: 'Autolink literals'}]\n    },\n    {\n      type: 'paragraph',\n      children: [\n        {\n          type: 'link',\n          title: null,\n          url: 'http://www.example.com',\n          children: [{type: 'text', value: 'www.example.com'}]\n        },\n        {type: 'text', value: ', '},\n        {\n          type: 'link',\n          title: null,\n          url: 'https://example.com',\n          children: [{type: 'text', value: 'https://example.com'}]\n        },\n        {type: 'text', value: ', and '},\n        {\n          type: 'link',\n          title: null,\n          url: 'mailto:contact@example.com',\n          children: [{type: 'text', value: 'contact@example.com'}]\n        },\n        {type: 'text', value: '.'}\n      ]\n    },\n    {type: 'heading', depth: 2, children: [{type: 'text', value: 'Footnote'}]},\n    {\n      type: 'paragraph',\n      children: [\n        {type: 'text', value: 'A note'},\n        {type: 'footnoteReference', identifier: '1', label: '1'}\n      ]\n    },\n    {\n      type: 'footnoteDefinition',\n      identifier: '1',\n      label: '1',\n      children: [\n        {type: 'paragraph', children: [{type: 'text', value: 'Big note.'}]}\n      ]\n    },\n    {\n      type: 'heading',\n      depth: 2,\n      children: [{type: 'text', value: 'Strikethrough'}]\n    },\n    {\n      type: 'paragraph',\n      children: [\n        {\n          type: 'delete',\n          children: [{type: 'text', value: 'one'}]\n        },\n        {type: 'text', value: ' or '},\n        {\n          type: 'delete',\n          children: [{type: 'text', value: 'two'}]\n        },\n        {type: 'text', value: ' tildes.'}\n      ]\n    },\n    {type: 'heading', depth: 2, children: [{type: 'text', value: 'Table'}]},\n    {\n      type: 'table',\n      align: [null, 'left', 'right', 'center'],\n      children: [\n        {\n          type: 'tableRow',\n          children: [\n            {type: 'tableCell', children: [{type: 'text', value: 'a'}]},\n            {type: 'tableCell', children: [{type: 'text', value: 'b'}]},\n            {type: 'tableCell', children: [{type: 'text', value: 'c'}]},\n            {type: 'tableCell', children: [{type: 'text', value: 'd'}]}\n          ]\n        }\n      ]\n    },\n    {type: 'heading', depth: 2, children: [{type: 'text', value: 'Tasklist'}]},\n    {\n      type: 'list',\n      ordered: false,\n      start: null,\n      spread: false,\n      children: [\n        {\n          type: 'listItem',\n          spread: false,\n          checked: false,\n          children: [\n            {type: 'paragraph', children: [{type: 'text', value: 'to do'}]}\n          ]\n        },\n        {\n          type: 'listItem',\n          spread: false,\n          checked: true,\n          children: [\n            {type: 'paragraph', children: [{type: 'text', value: 'done'}]}\n          ]\n        }\n      ]\n    }\n  ]\n}\n```\n\n```markdown\n# GFM\n\n## Autolink literals\n\n[www.example.com](http://www.example.com), \u003chttps://example.com\u003e, and \u003ccontact@example.com\u003e.\n\n## Footnote\n\nA note[^1]\n\n[^1]: Big note.\n\n## Strikethrough\n\n~~one~~ or ~~two~~ tildes.\n\n## Table\n\n| a | b  |  c |  d  |\n| - | :- | -: | :-: |\n\n## Tasklist\n\n*   [ ] to do\n*   [x] done\n```\n\n## API\n\nThis package exports the identifiers [`gfmFromMarkdown`][api-gfm-from-markdown]\nand [`gfmToMarkdown`][api-gfm-to-markdown].\nThere is no default export.\n\n### `gfmFromMarkdown()`\n\nCreate an extension for [`mdast-util-from-markdown`][mdast-util-from-markdown]\nto enable GFM (autolink literals, footnotes, strikethrough, tables, tasklists).\n\n###### Returns\n\nExtension for `mdast-util-from-markdown` to enable GFM\n([`Array\u003cFromMarkdownExtension\u003e`][from-markdown-extension]).\n\n### `gfmToMarkdown(options?)`\n\nCreate an extension for [`mdast-util-to-markdown`][mdast-util-to-markdown]\nto enable GFM (autolink literals, footnotes, strikethrough, tables, tasklists).\n\n###### Parameters\n\n* `options` ([`Options`][api-options])\n  — configuration\n\n###### Returns\n\nExtension for `mdast-util-to-markdown` to enable GFM\n([`Array\u003cToMarkdownExtension\u003e`][to-markdown-extension]).\n\n### `Options`\n\nConfiguration (TypeScript type).\n\n###### Fields\n\n* `firstLineBlank` (`boolean`, default: `false`)\n  — use a blank line for the first line of footnote definitions\n* `stringLength` (`((value: string) =\u003e number)`, default: `s =\u003e s.length`)\n  — function to detect the length of table cell content, used when aligning\n  the delimiters between cells\n* `tableCellPadding` (`boolean`, default: `true`)\n  — whether to add a space of padding between delimiters and cells\n* `tablePipeAlign` (`boolean`, default: `true`)\n  — whether to align the delimiters\n\n## HTML\n\nThis utility does not handle how markdown is turned to HTML.\nThat’s done by [`mdast-util-to-hast`][mdast-util-to-hast].\n\n## Syntax\n\nSee [Syntax in `micromark-extension-gfm`][syntax].\n\n## Syntax tree\n\nThis utility combines several mdast utilities.\nSee their readmes for the node types supported in the tree:\n\n* [`mdast-util-gfm-autolink-literal`](https://github.com/syntax-tree/mdast-util-gfm-autolink-literal#syntax-tree)\n  — GFM autolink literals\n* [`mdast-util-gfm-footnote`](https://github.com/syntax-tree/mdast-util-gfm-footnote#syntax-tree)\n  — GFM footnotes\n* [`mdast-util-gfm-strikethrough`](https://github.com/syntax-tree/mdast-util-gfm-strikethrough#syntax-tree)\n  — GFM strikethrough\n* [`mdast-util-gfm-table`](https://github.com/syntax-tree/mdast-util-gfm-table#syntax-tree)\n  — GFM tables\n* [`mdast-util-gfm-task-list-item`](https://github.com/syntax-tree/mdast-util-gfm-task-list-item#syntax-tree)\n  — GFM tasklists\n\n## Types\n\nThis package is fully typed with [TypeScript][].\nIt exports the additional type [`Options`][api-options].\n\nThe `Delete`, `FootnoteDefinition`, `FootnoteReference`, `Table`, `TableRow`,\nand `TableCell` types of the mdast nodes are exposed from `@types/mdast`.\n\n## Compatibility\n\nProjects maintained by the unified collective are compatible with maintained\nversions of Node.js.\n\nWhen we cut a new major release, we drop support for unmaintained versions of\nNode.\nThis means we try to keep the current release line, `mdast-util-gfm@^3`,\ncompatible with Node.js 16.\n\n## Related\n\n* [`remark-gfm`][remark-gfm]\n  — remark plugin to support GFM\n* [`micromark-extension-gfm`][extension]\n  — micromark extension to parse GFM\n\n## Contribute\n\nSee [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for\nways to get started.\nSee [`support.md`][support] for ways to get help.\n\nThis project has a [code of conduct][coc].\nBy interacting with this repository, organization, or community you agree to\nabide by its terms.\n\n## License\n\n[MIT][license] © [Titus Wormer][author]\n\n\u003c!-- Definitions --\u003e\n\n[api-gfm-from-markdown]: #gfmfrommarkdown\n\n[api-gfm-to-markdown]: #gfmtomarkdownoptions\n\n[api-options]: #options\n\n[author]: https://wooorm.com\n\n[backers-badge]: https://opencollective.com/unified/backers/badge.svg\n\n[build]: https://github.com/syntax-tree/mdast-util-gfm/actions\n\n[build-badge]: https://github.com/syntax-tree/mdast-util-gfm/workflows/main/badge.svg\n\n[chat]: https://github.com/syntax-tree/unist/discussions\n\n[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg\n\n[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md\n\n[collective]: https://opencollective.com/unified\n\n[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md\n\n[coverage]: https://codecov.io/github/syntax-tree/mdast-util-gfm\n\n[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/mdast-util-gfm.svg\n\n[downloads]: https://www.npmjs.com/package/mdast-util-gfm\n\n[downloads-badge]: https://img.shields.io/npm/dm/mdast-util-gfm.svg\n\n[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c\n\n[esmsh]: https://esm.sh\n\n[extension]: https://github.com/micromark/micromark-extension-gfm\n\n[from-markdown-extension]: https://github.com/syntax-tree/mdast-util-from-markdown#extension\n\n[gfm]: https://github.github.com/gfm/\n\n[health]: https://github.com/syntax-tree/.github\n\n[license]: license\n\n[mdast]: https://github.com/syntax-tree/mdast\n\n[mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown\n\n[mdast-util-frontmatter]: https://github.com/syntax-tree/mdast-util-frontmatter\n\n[mdast-util-to-hast]: https://github.com/syntax-tree/mdast-util-to-hast\n\n[mdast-util-to-markdown]: https://github.com/syntax-tree/mdast-util-to-markdown\n\n[npm]: https://docs.npmjs.com/cli/install\n\n[remark-gfm]: https://github.com/remarkjs/remark-gfm\n\n[size]: https://bundlejs.com/?q=mdast-util-gfm\n\n[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size\u0026query=$.size.compressedSize\u0026url=https://deno.bundlejs.com/?q=mdast-util-gfm\n\n[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg\n\n[support]: https://github.com/syntax-tree/.github/blob/main/support.md\n\n[syntax]: https://github.com/micromark/micromark-extension-gfm#syntax\n\n[to-markdown-extension]: https://github.com/syntax-tree/mdast-util-to-markdown#options\n\n[typescript]: https://www.typescriptlang.org\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsyntax-tree%2Fmdast-util-gfm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsyntax-tree%2Fmdast-util-gfm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsyntax-tree%2Fmdast-util-gfm/lists"}