markdown-it-footnote

What is markdown-it-footnote?

The markdown-it-footnote package is a plugin for the markdown-it Markdown parser that adds support for footnotes. It allows users to easily add footnotes to their Markdown documents, which are rendered as superscript numbers that link to the corresponding footnote text at the bottom of the document.

What are markdown-it-footnote's main functionalities?

Basic Footnote

This feature allows you to add a basic footnote to your Markdown text. The footnote reference is indicated by [^1] and the footnote text is provided at the bottom of the document.

const md = require('markdown-it')().use(require('markdown-it-footnote'));
const result = md.render('Here is a footnote reference[^1].

[^1]: Here is the footnote.');
console.log(result);

Inline Footnote

This feature allows you to add an inline footnote directly within the text. The inline footnote is indicated by ^[text] and the footnote text is provided within the brackets.

const md = require('markdown-it')().use(require('markdown-it-footnote'));
const result = md.render('Here is an inline footnote^[Here is the inline footnote text].');
console.log(result);

Multiple Footnotes

This feature allows you to add multiple footnotes to your Markdown text. Each footnote reference is indicated by a unique identifier [^1], [^2], etc., and the corresponding footnote text is provided at the bottom of the document.

const md = require('markdown-it')().use(require('markdown-it-footnote'));
const result = md.render('Here is a footnote reference[^1] and another one[^2].

[^1]: First footnote.
[^2]: Second footnote.');
console.log(result);

Other packages similar to markdown-it-footnote

markdown-it

markdown-it is a Markdown parser that is highly extensible and can be used with various plugins to add additional functionality, such as footnotes. It is the base parser that markdown-it-footnote extends.

remark-footnotes

remark-footnotes is a plugin for the remark Markdown processor that adds support for footnotes. It provides similar functionality to markdown-it-footnote but is used within the remark ecosystem.

markdown-it-attrs

markdown-it-attrs is a plugin for markdown-it that allows you to add attributes to Markdown elements. While it does not specifically handle footnotes, it can be used in conjunction with other plugins to enhance Markdown rendering.

README

markdown-it-footnote

Footnotes plugin for markdown-it markdown parser.

v2.+ requires markdown-it v5.+, see changelog.

Markup is based on pandoc definition.

Normal footnote:

Here is a footnote reference,[^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.

html:

<p>Here is a footnote reference,<sup class="footnote-ref"><a href="#fn1" id="fnref1">[1]</a></sup> and another.<sup class="footnote-ref"><a href="#fn2" id="fnref2">[2]</a></sup></p>
<p>This paragraph won’t be part of the note, because it
isn’t indented.</p>
<hr class="footnotes-sep">
<section class="footnotes">
<ol class="footnotes-list">
<li id="fn1"  class="footnote-item"><p>Here is the footnote. <a href="#fnref1" class="footnote-backref">↩</a></p>
</li>
<li id="fn2"  class="footnote-item"><p>Here’s one with multiple blocks.</p>
<p>Subsequent paragraphs are indented to show that they
belong to the previous footnote. <a href="#fnref2" class="footnote-backref">↩</a></p>
</li>
</ol>
</section>

Inline footnote:

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.]

html:

<p>Here is an inline note.<sup class="footnote-ref"><a href="#fn1" id="fnref1">[1]</a></sup></p>
<hr class="footnotes-sep">
<section class="footnotes">
<ol class="footnotes-list">
<li id="fn1"  class="footnote-item"><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="#fnref1" class="footnote-backref">↩</a></p>
</li>
</ol>
</section>

Install

node.js, browser:

npm install markdown-it-footnote --save
bower install markdown-it-footnote --save

Use

var md = require('markdown-it')()
            .use(require('markdown-it-footnote'));

md.render(/*...*/) // See examples above

Differences in browser. If you load script directly into the page, without package system, module will add itself globally as window.markdownitFootnote.

Customize

If you want to customize the output, you'll need to replace the template functions. To see which templates exist and their default implementations, look in index.js. The API of these template functions is out of scope for this plugin's documentation; you can read more about it in the markdown-it documentation.

To demonstrate with an example, here is how you might replace the <hr> that this plugin emits by default with an <h4> emitted by your own template function override:

const md = require('markdown-it')().use(require('markdown-it-footnote'));

md.renderer.rules.footnote_block_open = () => (
  '<h4 class="mt-3">Footnotes</h4>\n' +
  '<section class="footnotes">\n' +
  '<ol class="footnotes-list">\n'
);

Here's another example that customizes footnotes for epub books:

const backrefLabel = 'back to text';

const epubRules = {
  footnote_ref: ['<a', '<a epub:type="noteref"'],
  footnote_open: ['<li', '<li epub:type="footnote"'],
  footnote_anchor: ['<a', `<a aria-label="${backrefLabel}"`],
}

Object.keys(epubRules).map(rule => {
  let defaultRender = md.renderer.rules[rule];
  md.renderer.rules[rule] = (tokens, idx, options, env, self) => {
    return defaultRender(tokens, idx, options, env, self).replace(...epubRules[rule]);
  }
})

License

MIT