micromark-extension-gfm-footnote

micromark-extension-gfm-footnote

micromark extension to support GitHub Flavored Markdown (GFM) footnotes. 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

You should probably use micromark-extension-gfm instead, which combines this package with other GFM features. Alternatively, if you don’t want all of GFM, use this package.

Install

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

npm:

npm install micromark-extension-gfm-footnote

Use

Say we have the following file, example.md:

Using footnotes is fun![^1] They let you reference relevant information without disrupting the flow of what you’re trying to say.[^bignote]

[^1]: This is the first footnote.
[^bignote]: Here’s one with multiple paragraphs and code.

    Indent paragraphs to include them in the footnote.

    ```
    my code
    ```

    Add as many paragraphs as you like.

Text here and here and here.
[Learn more about markdown and footnotes in markdown](https://docs.github.com/en/github/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#footnotes)

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

import fs from 'node:fs'
import {micromark} from 'micromark'
import {gfmFootnote, gfmFootnoteHtml} from 'micromark-extension-gfm-footnote'

const output = micromark(fs.readFileSync('example.md'), {
  extensions: [gfmFootnote()],
  htmlExtensions: [gfmFootnoteHtml()]
})

console.log(output)

Now, running node example yields:

<p>Using footnotes is fun!<sup><a href="#user-content-fn-1" id="user-content-fnref-1" data-footnote-ref="" aria-describedby="footnote-label">1</a></sup> They let you reference relevant information without disrupting the flow of what you’re trying to say.<sup><a href="#user-content-fn-bignote" id="user-content-fnref-bignote" data-footnote-ref="" aria-describedby="footnote-label">2</a></sup></p>
<p>Text here and here and here.
<a href="https://docs.github.com/en/github/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#footnotes">Learn more about markdown and footnotes in markdown</a></p>
<section data-footnotes="" class="footnotes"><h2 id="footnote-label" class="sr-only">Footnotes</h2>
<ol>
<li id="user-content-fn-1">
<p>This is the first footnote. <a href="#user-content-fnref-1" data-footnote-backref="" class="data-footnote-backref" aria-label="Back to content">↩</a></p>
</li>
<li id="user-content-fn-bignote">
<p>Here’s one with multiple paragraphs and code.</p>
<p>Indent paragraphs to include them in the footnote.</p>
<pre><code>my code
</code></pre>
<p>Add as many paragraphs as you like. <a href="#user-content-fnref-bignote" data-footnote-backref="" class="data-footnote-backref" aria-label="Back to content">↩</a></p>
</li>
</ol>
</section>

API

This package exports the following identifiers: gfmFootnote, gfmFootnoteHtml. There is no default export.

The export map supports the endorsed development condition. Run node --conditions development module.js to get instrumented dev code. Without this condition, production code is loaded.

gfmFootnote()

gfmFootnoteHtml(htmlOptions)

A function that can be called to get an extension for micromark to parse GFM footnotes (can be passed in extensions) and a function that can be called to get an extension to compile them to HTML (can be passed in htmlExtensions).

htmlOptions.clobberPrefix

Prefix to use before the id attribute to prevent it from clobbering attributes (string, default: 'user-content-'). DOM clobbering is this:

<p id=x></p>
<script>alert(x)</script>

Elements by their ID are made available in browsers on the window object. Using a prefix this that from being a problem.

htmlOptions.label

Label to use for the footnotes section (string, default: 'Footnotes'). Affects screen reader users. Change it if you’re authoring in a different language.

htmlOptions.backLabel

Label to use from backreferences back to their footnote call (string, default: 'Back to content'). Affects screen reader users. Change it if you’re authoring in a different language.

Recommended CSS

The following CSS is needed to make footnotes look a bit like GitHub. For the complete actual CSS see sindresorhus/github-markdown-css.

/* Style the footnotes section. */
.footnotes {
  font-size: smaller;
  color: #8b949e;
  border-top: 1px solid #30363d;
}

/* Hide the section label for visual users. */
.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  word-wrap: normal;
  border: 0;
}

/* Place `[` and `]` around footnote calls. */
[data-footnote-ref]::before {
  content: '[';
}

[data-footnote-ref]::after {
  content: ']';
}

Related

• remarkjs/remark — markdown processor powered by plugins
• remarkjs/remark-gfm — remark plugin using this to support all of GFM
• micromark/micromark — the smallest commonmark-compliant markdown parser that exists
• syntax-tree/mdast-util-gfm-footnote — mdast utility to support 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 micromark/.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