mdast-util-gfm-footnote

What is mdast-util-gfm-footnote?

The mdast-util-gfm-footnote npm package is a utility to support GitHub Flavored Markdown (GFM) footnotes in mdast, which is a Markdown Abstract Syntax Tree format. It allows for parsing and serializing footnote syntax as specified in GFM, making it easier to handle footnotes in Markdown files programmatically.

What are mdast-util-gfm-footnote's main functionalities?

Parsing GFM footnotes

This feature allows the parsing of GFM footnotes in Markdown text. The code sample demonstrates how to set up a processor with unified, using the remark-parse and remark-gfm plugins along with mdast-util-gfm-footnote to parse a Markdown string containing a footnote.

import { unified } from 'unified';
import markdown from 'remark-parse';
import gfm from 'remark-gfm';
import gfmFootnote from 'mdast-util-gfm-footnote';

const processor = unified()
  .use(markdown)
  .use(gfm)
  .use(gfmFootnote);

const ast = processor.parse('[^1]: This is a footnote.');
console.log(ast);

Serializing GFM footnotes

This feature supports the serialization of GFM footnotes back into Markdown format. The code sample shows how to configure a unified processor to convert an AST with a footnote definition back into a Markdown string.

import { unified } from 'unified';
import markdown from 'remark-parse';
import gfm from 'remark-gfm';
import gfmFootnote from 'mdast-util-gfm-footnote';
import stringify from 'remark-stringify';

const processor = unified()
  .use(markdown)
  .use(gfm)
  .use(gfmFootnote)
  .use(stringify);

const ast = { type: 'footnoteDefinition', identifier: '1', children: [{ type: 'paragraph', children: [{ type: 'text', value: 'This is a footnote.' }] }] };
const markdownText = processor.stringify(ast);
console.log(markdownText);

Other packages similar to mdast-util-gfm-footnote

remark-footnotes

remark-footnotes is a plugin for the remark Markdown processor that adds support for footnotes. It is similar to mdast-util-gfm-footnote but is specifically designed to work within the remark ecosystem. While mdast-util-gfm-footnote focuses on GFM-specific footnote syntax, remark-footnotes offers a more general approach to footnotes in Markdown.

remark-gfm

remark-gfm is another plugin for remark that adds support for GitHub Flavored Markdown. It includes support for tables, strikethrough, task lists, and URLs directly. While it also supports footnotes as part of its GFM support, mdast-util-gfm-footnote provides more specialized and detailed handling of footnotes in the context of GFM.

README

mdast-util-gfm-footnote

Extension for mdast-util-from-markdown and/or mdast-util-to-markdown to support GitHub flavored markdown (GFM) footnotes in mdast. When parsing (from-markdown), must be combined with micromark-extension-gfm-footnote.

GFM footnotes were announced September 30, 2021 but are neither specified nor supported in all their products (e.g., Gists). Their implementation on github.com is currently quite buggy. The bugs have been reported on cmark-gfm. This micromark extension matches github.com except for its bugs.

When to use this

Use mdast-util-gfm if you want all of GFM. Use this otherwise.

Install

This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required.

npm:

npm install mdast-util-gfm-footnote

Use

Say our module, example.js, looks as follows:

import {fromMarkdown} from 'mdast-util-from-markdown'
import {toMarkdown} from 'mdast-util-to-markdown'
import {gfmFootnote} from 'micromark-extension-gfm-footnote'
import {gfmFootnoteFromMarkdown, gfmFootnoteToMarkdown} from 'mdast-util-gfm-footnote'

const doc = 'Hi![^1]\n\n[^1]: big note'

const tree = fromMarkdown(doc, {
  extensions: [gfmFootnote()],
  mdastExtensions: [gfmFootnoteFromMarkdown()]
})

console.log(tree)

const out = toMarkdown(tree, {extensions: [gfmFootnoteToMarkdown()]})

console.log(out)

Now, running node example yields:

{
  type: 'root',
  children: [
    {
      type: 'paragraph',
      children: [
        {type: 'text', value: 'Hi!'},
        {type: 'footnoteReference', identifier: '1', label: '1'}
      ]
    },
    {
      type: 'footnoteDefinition',
      identifier: '1',
      label: '1',
      children: [
        {type: 'paragraph', children: [{type: 'text', value: 'big note'}]}
      ]
    }
  ]
}

Hi\![^1]

[^1]: big note

API

gfmFootnoteFromMarkdown()

gfmFootnoteToMarkdown()

Support footnotes. The exports are functions that can be called to get extensions, respectively for mdast-util-from-markdown and mdast-util-to-markdown.

Related

• remarkjs/remark — markdown processor powered by plugins
• remarkjs/remark-gfm — remark plugin to support GFM
• micromark/micromark — the smallest commonmark-compliant markdown parser that exists
• micromark/micromark-extension-gfm-footnote — micromark extension to parse GFM footnotes
• syntax-tree/mdast-util-from-markdown — mdast parser using micromark to create mdast from markdown
• syntax-tree/mdast-util-to-markdown — mdast serializer to create markdown from mdast

Contribute

See contributing.md in syntax-tree/.github for ways to get started. See support.md for ways to get help.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

License

MIT © Titus Wormer