micromark-extension-gfm-footnote

micromark-extension-gfm-footnote adds GitHub Flavored Markdown footnote support to micromark, the small, fast, and safe streaming markdown tokenizer that powers remark and the unified ecosystem. It provides a syntax extension that teaches micromark’s state machine to recognize footnote references and definitions, plus an HTML extension that compiles those tokens into the same footnote markup GitHub produces.

Because it operates at the token level, it is the lowest layer of the footnote stack: when you also need a syntax tree you pair it with mdast-util-gfm-footnote, and when you want all of GFM you use micromark-extension-gfm. It matches github.com behavior (aside from documented upstream bugs) and supports configurable label text for localization.

What You Get

• A gfmFootnote() syntax extension that tokenizes footnote references and definitions
• A gfmFootnoteHtml() HTML extension that compiles footnotes to GitHub-compatible markup
• Configurable label and back-reference text for localization and accessibility
• Behavior matched to github.com’s footnote implementation
• TypeScript types and a development build with debugging assertions

Common Use Cases

• Adding footnote support when using micromark directly to render markdown to HTML
• Serving as the tokenizer layer beneath mdast-util-gfm-footnote in a unified pipeline
• Building custom markdown-to-HTML tooling that needs GFM footnotes
• Localizing footnote section labels and back-link titles

Under The Hood

Architecture - The package ships two extensions. dev/lib/syntax.js (~558 lines) defines micromark constructs and state-machine tokenizers that recognize footnote definition labels and inline references, wiring into micromark’s document and text content types. dev/lib/html.js (~226 lines) is an HTML compiler extension that buffers footnote calls and emits a numbered footnotes section with back-references at the end of the document. A dev build keeps assertions while the published build strips them.

Tech Stack - Pure ESM JavaScript typed via JSDoc, built on micromark’s low-level construct/tokenizer primitives (micromark-util-* helpers). It targets modern Node.js and browsers and ships both a dev and production build.

Code Quality - The code follows micromark’s rigorous, character-level conventions with an extensive test suite comparing output against reference fixtures. The tokenizer is dense but methodical, reflecting the exacting nature of streaming markdown parsing.

API Design - The two-function syntax/HTML split matches every other micromark extension, so it plugs into micromark’s extensions/htmlExtensions option arrays with no new concepts. Options are limited but meaningful, chiefly localizable label text.