@gerhobbelt/markdown-it-footnote

Footnotes for markdown-it markdown parser.

Stats

StarsIssuesVersionUpdatedCreatedSize
@gerhobbelt/markdown-it-footnote
003.0.3-127 months ago4 years agoMinified + gzip package size for @gerhobbelt/markdown-it-footnote in KB

Readme

markdown-it-footnote

Node.js CI CircleCI NPM version Coverage Status

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>

Footnote with added text:

This fork adds support for footnote references having additional text content. This type of footnote reference follows the pattern of [^l ...] where l is a one-word label, followed by a space and then some additional text. You might prefer to use this way of referencing a footnote in order to enhance usability in certain accessibility scenarios: when a screen reader user is navigating a document as list of links for example (where the links are presented separately from the surrounding document) it is more useful to hear the footnote link described as "added text [1]" rather than just "[1]".

Here is a footnote reference with [^1 added text].

[^1]: Here is the footnote.

html:

<p>Here is a footnote reference with <a href="#fn1" id="fnref1">added text<sup class="footnote-ref">[1]</sup></a>.</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>
</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 @gerhobbelt/markdown-it-footnote --save
bower install @gerhobbelt/markdown-it-footnote --save

Use

var md = require('@gerhobbelt/markdown-it')()
            .use(require('@gerhobbelt/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.

Options

atDocumentEnd: true/false (default: true) - where to generate the footnotes.

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'
);

License

MIT

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.