@inclusive-design/eleventy-plugin-inclusive-footnotes 1.0.0

package/.markdownlint-cli2.mjs

@@ -0,0 +1,10 @@
+import markdownlintConfig from '@inclusive-design/markdownlint-config';
+
+export default {
+	config: Object.assign(markdownlintConfig.config, {
+		'no-hard-tabs': {
+			code_blocks: false,
+		},
+	}),
+	ignores: ['node_modules', 'CHANGELOG.md', 'fixtures/**/*.md'],
+};

package/.nvmrc

@@ -0,0 +1 @@
+24

package/.zed/settings.json

@@ -0,0 +1,13 @@
+{
+  "languages": {
+    "JavaScript": {
+      "formatter": [],
+      "code_actions_on_format": {
+        "source.fixAll.eslint": true
+      },
+      "language_servers": [
+        "!biome"
+      ]
+    }
+  }
+}

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## [1.0.0](https://github.com/inclusive-design/eleventy-plugin-inclusive-footnotes/compare/v0.1.0...v1.0.0) (2026-03-23)
+
+
+### Features
+
+* initial commit ([fe4498f](https://github.com/inclusive-design/eleventy-plugin-inclusive-footnotes/commit/fe4498f0889b5b00a3d4a6cb467bacb32eb2ab64))
+
+
+### Bug Fixes
+
+* rename workflow ([#9](https://github.com/inclusive-design/eleventy-plugin-inclusive-footnotes/issues/9)) ([1be9d7c](https://github.com/inclusive-design/eleventy-plugin-inclusive-footnotes/commit/1be9d7c77b55dd003ca1f3d800c309393e39b1e8))
+* resolve linting issue ([#5](https://github.com/inclusive-design/eleventy-plugin-inclusive-footnotes/issues/5)) ([a4b8a28](https://github.com/inclusive-design/eleventy-plugin-inclusive-footnotes/commit/a4b8a28c34acddf07989c639beed586f4eaceb58))
+* resolve linting issues, configure husky, add a test ([#3](https://github.com/inclusive-design/eleventy-plugin-inclusive-footnotes/issues/3)) ([b1dba7a](https://github.com/inclusive-design/eleventy-plugin-inclusive-footnotes/commit/b1dba7a71d4cb4a6eca9998ebbd46466d4cef9e6))
+
+
+### Miscellaneous Chores
+
+* **release:** release 1.0.0 ([#13](https://github.com/inclusive-design/eleventy-plugin-inclusive-footnotes/issues/13)) ([ecfe1f8](https://github.com/inclusive-design/eleventy-plugin-inclusive-footnotes/commit/ecfe1f8a14c99332062b65e739cd4e83f1138be9))

package/README.md

@@ -0,0 +1,129 @@
+# 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)

package/commitlint.config.js

@@ -0,0 +1,5 @@
+const commitlintConfig = {
+	extends: ['@commitlint/config-conventional'],
+};
+
+export default commitlintConfig;

package/index.js

@@ -0,0 +1,73 @@
+import {Merge as eleventyMerge} from '@11ty/eleventy-utils';
+import {I18n} from 'i18n-js';
+import translations from './localization/translations.json' with {type: 'json'};
+import markdownItFootnote from 'markdown-it-footnote';
+
+const inclusiveFootnotesPlugin = {
+	configFunction(eleventyConfig, options = {}) {
+		options = eleventyMerge({
+			headingLevel: 2,
+			translations,
+		}, options);
+
+		const i18n = new I18n(options.translations);
+
+		eleventyConfig.addGlobalData('footnotesHeadingLevel', options.headingLevel);
+
+		eleventyConfig.amendLibrary('md', md => {
+			md.use(markdownItFootnote);
+
+			md.renderer.rules.footnote_caption = (tokens, index, _options, _environment, _slf) => (Number(tokens[index].meta.id + 1).toString());
+
+			md.renderer.rules.footnote_ref = (tokens, index, options, environment, slf) => {
+				i18n.locale = environment.lang ?? 'en';
+
+				const id = slf.rules.footnote_anchor_name(tokens, index, options, environment, slf);
+				const caption = slf.rules.footnote_caption(tokens, index, options, environment, slf);
+				let refid = id;
+
+				if (tokens[index].meta.subId > 0) {
+					refid += `:${tokens[index].meta.subId}`;
+				}
+
+				return (`<sup class="footnote-ref"><a href="#fn${id}" role="doc-noteref" id="fnref${refid}" aria-label="${i18n.t('footnote_ref', {id})}">${caption}</a></sup>`);
+			};
+
+			md.renderer.rules.footnote_block_open = (_tokens, _index, options, environment, _slf) => {
+				i18n.locale = environment.lang ?? 'en';
+
+				return (
+					`<section class="footnotes" role="doc-endnotes" aria-labelledby="footnotes">
+					<h${environment.footnotesHeadingLevel} id="footnotes">${i18n.t('footnotes')}</h${environment.footnotesHeadingLevel}>
+					<ol class="footnotes-list">`
+				);
+			};
+
+			md.renderer.rules.footnote_open = (tokens, index, options, environment, slf) => {
+				let id = slf.rules.footnote_anchor_name(tokens, index, options, environment, slf);
+
+				if (tokens[index].meta.subId > 0) {
+					id += `:${tokens[index].meta.subId}`;
+				}
+
+				return (`<li id="fn${id}" role="doc-endnote" class="footnote-item">`);
+			};
+
+			md.renderer.rules.footnote_anchor = (tokens, index, options, environment, slf) => {
+				i18n.locale = environment.lang ?? 'en';
+
+				let id = slf.rules.footnote_anchor_name(tokens, index, options, environment, slf);
+				const label = i18n.t('backlink', {ref: tokens[index].meta.subId + 1, footnote: id});
+
+				if (tokens[index].meta.subId > 0) {
+					id += `:${tokens[index].meta.subId}`;
+				}
+
+				/* ↩ with escape code to prevent display as Apple Emoji on iOS */
+				return (`<a href="#fnref${id}" role="doc-backlink" class="footnote-backref" aria-label="${label}">\u21A9\uFE0E</a>`);
+			};
+		});
+	},
+};
+
+export default inclusiveFootnotesPlugin;

package/localization/translations.json

@@ -0,0 +1,12 @@
+{
+  "en": {
+    "footnote_ref": "Footnote %{id}",
+		"footnotes": "Footnotes",
+		"backlink": "Back to reference %{ref} for footnote %{footnote}"
+	},
+	"fr": {
+		"footnote_ref": "Note de bas de page %{id}",
+		"footnotes": "Notes de bas de page",
+		"backlink": "Retourner à la référence %{ref} pour la note de bas de page %{footnote}"
+	}
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@inclusive-design/eleventy-plugin-inclusive-footnotes",
+  "version": "1.0.0",
+  "description": "This plugin improves accessibility of HTML generated by the markdown-it-footnotes plugin for Eleventy.",
+  "main": "index.js",
+  "type": "module",
+  "scripts": {
+    "lint": "run-s lint:*",
+    "lint:eslint": "eslint",
+    "lint:markdownlint": "markdownlint-cli2 \"**/*.md\"",
+    "start": "eleventy --serve",
+    "test": "node --test",
+    "prepare": "husky"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/inclusive-design/eleventy-plugin-inclusive-footnotes.git"
+  },
+  "keywords": [
+    "11ty",
+    "markdown-it",
+    "footnotes"
+  ],
+  "author": "OCAD University <idrc@ocadu.ca>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/inclusive-design/eleventy-plugin-inclusive-footnotes/issues"
+  },
+  "homepage": "https://github.com/inclusive-design/eleventy-plugin-inclusive-footnotes#readme",
+  "dependencies": {
+    "@11ty/eleventy-utils": "^2.0.7",
+    "i18n-js": "^4.5.3",
+    "markdown-it-footnote": "^4.0.0"
+  },
+  "devDependencies": {
+    "@11ty/eleventy": "^3.1.2",
+    "@commitlint/cli": "^20.5.0",
+    "@commitlint/config-conventional": "^20.5.0",
+    "@inclusive-design/eslint-config": "^0.3.0",
+    "@inclusive-design/markdownlint-config": "^0.1.0",
+    "eslint": "^10.0.3",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.4.0",
+    "markdownlint-cli2": "^0.22.0",
+    "npm-run-all2": "^8.0.4"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "lint-staged": {
+    "*.{cjs,js,json,mjs}": [
+      "eslint --fix"
+    ],
+    "*.md": [
+      "eslint --fix",
+      "markdownlint-cli2 --fix"
+    ]
+  }
+}

package/tests/references.test.js

@@ -0,0 +1,16 @@
+import assert from 'node:assert';
+import {beforeEach, test} from 'node:test';
+import fs from 'node:fs';
+import Eleventy from '@11ty/eleventy';
+
+beforeEach(async () => {
+	const elev = new Eleventy('.', '_site', {
+		quietMode: true,
+	});
+	await elev.write();
+});
+
+test('References have appropriate role', async () => {
+	const indexPage = fs.readFileSync('_site/index.html', 'utf8');
+	assert.ok(indexPage.includes('<a href="#fn1" role="doc-noteref"'));
+});