micromark-extension-footnote

micromark extension to support footnotes.

As there is no spec for footnotes in markdown, this extension stays as close to references and list items in CommonMark, while being inspired by the HTML output of Pandoc notes.

When to use this

If you’re using micromark or mdast-util-from-markdown, use this package. Alternatively, if you’re using remark, use remark-footnotes.

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-footnote

Use

Say we have the following file, example.md:

Here is a footnote call,[^1] and another.[^longnote]

[^1]: Here is the footnote.

[^longnote]: Here’s one with multiple blocks.

    Subsequent paragraphs are indented to show that they
belong to the previous footnote.

        { some.code }

    The whole paragraph can be indented, or just the first
    line.  In this way, multi-paragraph footnotes work like
    multi-paragraph list items.

This paragraph won’t be part of the note, because it
isn’t indented.

Here is an inline note.^[Inlines notes are easier to write, since
you don’t have to pick an identifier and move down to type the
note.]

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

import fs from 'fs'
import {micromark} from 'micromark'
import {footnote, footnoteHtml} from 'micromark-extension-footnote'

const output = micromark(fs.readFileSync('example.md'), {
  extensions: [footnote({inlineNotes: true})],
  htmlExtensions: [footnoteHtml]
})

console.log(output)

Now, running node example yields:

<p>Here is a footnote call,<a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a> and another.<a href="#fn2" class="footnote-ref" id="fnref2" role="doc-noteref"><sup>2</sup></a></p>
<p>This paragraph won’t be part of the note, because it
isn’t indented.</p>
<p>Here is an inline note.<a href="#fn3" class="footnote-ref" id="fnref3" role="doc-noteref"><sup>3</sup></a></p>
<section class="footnotes" role="doc-endnotes">
<hr />
<ol>
<li id="fn1" role="doc-endnote">
<p>Here is the footnote.<a href="#fnref1" class="footnote-back" role="doc-backlink">↩</a></p>
</li>
<li id="fn2" role="doc-endnote">
<p>Here’s one with multiple blocks.</p>
<p>Subsequent paragraphs are indented to show that they
belong to the previous footnote.</p>
<pre><code>{ some.code }
</code></pre>
<p>The whole paragraph can be indented, or just the first
line.  In this way, multi-paragraph footnotes work like
multi-paragraph list items.<a href="#fnref2" class="footnote-back" role="doc-backlink">↩</a></p>
</li>
<li id="fn3" role="doc-endnote">
<p>Inlines notes are easier to write, since
you don’t have to pick an identifier and move down to type the
note.<a href="#fnref3" class="footnote-back" role="doc-backlink">↩</a></p>
</li>
</ol>
</section>

API

This package exports the following identifiers: footnote, footnoteHtml. 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.

`footnote(options?)`

`footnoteHtml`

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

`options.inlineNotes`

Whether to support ^[inline notes] (boolean, default: false).

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

hvitgar / micromark-extension-footnote Goto Github PK