mdast-util-gfm-footnote

mdast-util-gfm-footnote is part of the unified/syntax-tree ecosystem and provides two extensions that add GitHub Flavored Markdown footnote support to mdast, the markdown abstract syntax tree. One extension plugs into mdast-util-from-markdown to parse footnote definitions and references into tree nodes, and the other plugs into mdast-util-to-markdown to serialize those nodes back to markdown.

It handles the footnoteDefinition and footnoteReference node types, keeping the syntax tree lossless across a parse-and-stringify round trip. It is typically combined with micromark-extension-gfm-footnote for tokenization, and is one of the building blocks used by mdast-util-gfm and remark-gfm.

What You Get

• A from-markdown extension that parses footnote references and definitions into mdast nodes
• A to-markdown extension that serializes footnote nodes back to GFM markdown
• Support for the footnoteDefinition and footnoteReference node types
• Configurable serialization via ToMarkdownOptions
• TypeScript type definitions and lossless round-tripping of footnote syntax

Common Use Cases

• Adding footnote support to a remark or unified markdown pipeline
• Parsing GFM footnotes into an mdast tree for programmatic transformation
• Serializing generated footnote nodes back into markdown documents
• Building custom GFM tooling alongside micromark-extension-gfm-footnote

Under The Hood

Architecture - The package is implemented in a single lib/index.js (~226 lines) that exports two objects. The from-markdown extension registers enter/exit handlers keyed to micromark footnote token types, assembling footnoteReference and footnoteDefinition nodes on the mdast tree. The to-markdown extension supplies node handlers plus escape/unsafe rules so footnotes serialize correctly and identifiers are preserved.

Tech Stack - Pure ESM JavaScript typed via JSDoc with generated index.d.ts declarations. It depends on sibling unist/mdast utilities (mdast-util-from-markdown, mdast-util-to-markdown, micromark-util-* helpers) and targets modern Node.js and browsers.

Code Quality - The code follows the strict, uniform conventions of the syntax-tree project, with a dedicated test.js suite and full type coverage. Handlers are small and declarative, mapping cleanly between token events and tree nodes.

API Design - The two-function, from/to naming mirrors every other mdast-util extension, so anyone familiar with the ecosystem can adopt it instantly. It composes by being passed into from-markdown/to-markdown option arrays, requiring no bespoke wiring beyond the standard extension pattern.