mdast-util-gfm

mdast-util-gfm is a small aggregator package from the syntax-tree/unified collective that bundles GitHub Flavored Markdown (GFM) support into mdast, the markdown abstract syntax tree used across the unified/remark ecosystem. Rather than implementing GFM parsing itself, it composes five sibling extension packages — autolink literals, footnotes, strikethrough, tables, and tasklists — behind two functions, gfmFromMarkdown() and gfmToMarkdown(options), that plug directly into mdast-util-from-markdown and mdast-util-to-markdown.

It is the same GFM layer that powers remark-gfm, so projects that need the individual mdast-util-from-markdown/to-markdown building blocks (rather than remark’s higher-level plugin API) can pull in this one package instead of wiring the five extensions together by hand. It must be paired with micromark-extension-gfm for the underlying token-level parsing; this package only handles the mdast (tree) layer.

What You Get

• gfmFromMarkdown() — a ready-made array of mdast-util-from-markdown extensions enabling all five GFM syntaxes at once
• gfmToMarkdown(options) — a matching to-markdown extension for serializing GFM mdast nodes back into markdown text
• Table serialization options (tablePipeAlign, tableCellPadding, stringLength) forwarded from mdast-util-gfm-table
• Footnote serialization options (firstLineBlank) forwarded from mdast-util-gfm-footnote
• Full TypeScript types via JSDoc, with an exported Options interface merging the footnote and table option types

Common Use Cases

• Building a custom markdown processor on mdast-util-from-markdown/to-markdown that needs GFM without adopting the full remark plugin pipeline
• Parsing GitHub-flavored README/issue/PR content into an mdast tree for static-site generators or documentation tooling
• Round-tripping markdown (parse then re-serialize) while preserving GFM constructs like tables and tasklists
• Rendering GFM markdown to HTML by parsing with gfmFromMarkdown() and transforming the resulting mdast with mdast-util-to-hast

Under The Hood

Architecture The package is a thin composition/façade layer: index.js re-exports lib/index.js, whose entire logic is two functions, gfmFromMarkdown() and gfmToMarkdown(options), that call into and aggregate the extension objects returned by five sibling mdast-util-gfm-* packages (autolink-literal, footnote, strikethrough, table, task-list-item) into the array/object shapes mdast-util-from-markdown and mdast-util-to-markdown expect. There is no branching, state, or internal abstraction beyond delegation, so the architecture’s only real dependency risk is staying in lockstep with the extension contract of its five siblings and of mdast-util-from-markdown/to-markdown itself.

Tech Stack Written as ESM-only JavaScript (type: module) targeting Node.js 16+, with no runtime bundler — it ships raw source and relies on JSDoc-derived TypeScript declarations (index.d.ts) built separately via tsc and enforced with 100%-strict type-coverage. Its production dependencies are exactly the five mdast-util-gfm-* extension packages plus mdast-util-from-markdown and mdast-util-to-markdown; devDependencies bring in xo (ESLint) and prettier for linting/formatting, remark-cli with remark-preset-wooorm for self-linting the README, micromark-extension-gfm and mdast-util-to-hast/hast-util-to-html for integration-testing the full parse-to-HTML round trip, and c8 plus Node’s built-in test runner for coverage.

Code Quality test/index.js drives a CommonMark/GFM-style fixture table (test/spec.js) through fromMarkdown → toHast → toHtml and through toMarkdown, comparing output against golden fixtures under test/fixture/ for both HTML rendering and markdown round-tripping, plus dedicated tests for footnote and table serialization options. Coverage is enforced with c8 —100, type coverage is enforced at 100% strict, and CI (GitHub Actions) runs the suite across multiple Node versions with codecov reporting. Because the package itself contains almost no logic, testing is necessarily integration-style against the composed extensions rather than unit-style against internal branches.

API Design The public surface is deliberately minimal — exactly two named exports, gfmFromMarkdown() (no arguments) and gfmToMarkdown(options?) — which makes onboarding nearly instant for anyone already using mdast-util-from-markdown/to-markdown: drop the extension arrays into the existing extensions/mdastExtensions options and GFM support is enabled. The one merged Options type (combining the footnote and table option interfaces) keeps configuration discoverable without needing to know which sub-package a given option originated from.