npm package: @inclusive-design/eleventy-plugin-inclusive-footnotes
Description: This plugin improves accessibility of HTML generated by the markdown-it-footnotes plugin for Eleventy.
Author: OCAD University
Latest version: 1.0.0

# 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](#localization) `aria-label`.
- The footnote container is a `<section>` with the `doc-endnotes` role.
- The footnote container has a [localized](#localization) heading which is semantically linked to the container with `aria-labelledby`.
- The footnote container heading's heading level can be [customized](#customization).
- Footnotes have the `doc-endnote` role.
- Backlinks to footnote references have the `doc-backlink` role and a [localized](#localization) `aria-label`.

## Usage

Install the plugin in your project:

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

Add it to your Eleventy configuration file:

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

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

Use footnotes in a Markdown file:

```markdown
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:

```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:

```js
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](localization/translations.json)).

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

```js
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](https://kittygiraudel.com/blog/search/?q=footnotes)'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](https://github.com/11ty/eleventy-utils)
- [i18n-js](https://github.com/fnando/i18n)
- [markdown-it-footnote](https://github.com/markdown-it/markdown-it-footnote)