Inclusive Footnotes for Eleventy

This plugin improves accessibility of HTML generated by the markdown-it-footnotes plugin while maintaining the ease of authoring provided by Markdown footnotes. This plugin adds the following features:

• Footnote references have the doc-noteref role and a localized aria-label.
• The footnote container is a <section> with the doc-endnotes role.
• The footnote container has a localized heading which is semantically linked to the container with aria-labelledby.
• The footnote container heading's heading level can be customized.
• Footnotes have the doc-endnote role.
• Backlinks to footnote references have the doc-backlink role and a localized aria-label.

Usage

Install the plugin in your project:

npm i --save @inclusive-design/eleventy-plugin-inclusive-footnotes

Add it to your Eleventy configuration file:

import inclusiveFootnotesPlugin from "@inclusive-design/eleventy-plugin-inclusive-footnotes";

export default function (eleventyConfig) {
  eleventyConfig.addPlugin(inclusiveFootnotesPlugin);
};

Use footnotes in a Markdown file:

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

Here is another reference[^1] to the first footnote.

[^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.

Here is the resulting HTML:

<p>Here is a footnote reference,<sup class="footnote-ref"><a href="#fn1" role="doc-noteref" id="fnref1" aria-label="Footnote 1">1</a></sup> and another.<sup class="footnote-ref"><a href="#fn2" role="doc-noteref" id="fnref2" aria-label="Footnote 2">2</a></sup></p>

<p>Here is another reference<sup class="footnote-ref"><a href="#fn1" role="doc-noteref" id="fnref1:1" aria-label="Footnote 1">1</a></sup> to the first footnote.</p>

<section class="footnotes" role="doc-endnotes" aria-labelledby="footnotes">
	<h2 id="footnotes">Footnotes</h2>
	<ol class="footnotes-list">
	  <li id="fn1" role="doc-endnote" class="footnote-item">
			<p>Here is the footnote.<a href="#fnref1" role="doc-backlink" class="footnote-backref" aria-label="Back to reference 1 for footnote 1">↩︎</a><a href="#fnref1:1" role="doc-backlink" class="footnote-backref" aria-label="Back to reference 2 for footnote 1">↩︎</a></p>
		</li>
		<li id="fn2" role="doc-endnote" 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" role="doc-backlink" class="footnote-backref" aria-label="Back to reference 1 for footnote 2">↩︎</a></p>
		</li>
	</ol>
</section>

Customization

There are two options when adding the plugin.

The headingLevel option can be used to change the footnotes container's heading level from the default (2). For example, if the footnotes section should have an <h3>, add the plugin with the following configuration:

import inclusiveFootnotesPlugin from "@inclusive-design/eleventy-plugin-inclusive-footnotes";

export default function (eleventyConfig) {
  eleventyConfig.addPlugin(inclusiveFootnotesPlugin, {
  	headingLevel: 3
  });
};

The translations option allows the default localizations to be supplemented or overridden.

Localization

The plugin's three strings are localized in French and English (the translations can be found in translations.json).

To supplement or override the default translations, pass your translations to the translations option:

import inclusiveFootnotesPlugin from "@inclusive-design/eleventy-plugin-inclusive-footnotes";

export default function (eleventyConfig) {
  eleventyConfig.addPlugin(inclusiveFootnotesPlugin, {
  	translations: {
      en: {
     		footnote_ref: "Endnote %{id}",
     		footnotes: "Endnotes",
     		backlink: "Back to reference %{ref} for endnote %{footnote}"
      },
      de: {
        footnote_ref: "Endnote %{id}",
        footnotes: "Endnoten",
        backlink: "Zurück zur Referenz %{ref} für Endnote %{footnote}"
      }
    }
  });
};

This example changes the English strings to use "endnote" and "endnotes" instead of "footnote" and "footnotes" and adds German localization. Because the French strings are not provided, the default French translations will be used.

Credits

Kitty Giraudel's writing on accessible footnotes was essential for the development of this plugin.

Third Party Software in @inclusive-design/eleventy-plugin-inclusive-footnotes

@inclusive-design/eleventy-plugin-inclusive-footnotes is based on other publicly available software, categorized by license:

MIT License

• @11ty/eleventy-utils
• i18n-js
• markdown-it-footnote