setting up markdown-it-footnote to be like 10% more accessible

my hatred of 11ty shortcodes in markdown is going to kill me, dudea website post about websites7 min read

If you’re here, it’s be­cause you, like me, dis­like putting short­codes in your mark­down, so you’re us­ing mark­down-it-foot­note in­stead of the cor­rectly-ac­ces­si­ble op­tion. You prob­a­bly have far saner rea­sons than I, but this does mean we’re both us­ing some­thing that, from the stand­point of “can every­one read this in an equally com­pre­hen­sive amount”, is kind of ass for our foot­notes.

let’s make it slightly less ass

Permalink to “let’s make it slightly less ass”

First things first, you’ll need a CSS class that lets you hide shit. I yoinked the ex­am­ple from a11ypro­ject for mine, class name and all:

.visually-hidden:not(:focus):not(:active) {
    clip: rect(0 0 0 0);
    clip-path: inset(50%);
    height: 1px;
    overflow: hidden;
    position: absolute;
    white-space: nowrap;
    width: 1px;

Once you do that, you’re go­ing to re­place the fuck out of some rules. Here’s an ex­tremely culled con­fig of what that might look like:

const md = require("markdown-it");
const footnotes = require("markdown-it-footnote");

const options = {
		html: true,
		breaks: true,
		linkify: false,
		typographer: true,
const mdengine = md(options).use(footnotes)

mdengine.renderer.rules.footnote_ref = (tokens, idx, options, env, slf) => {
	const id = slf.rules.footnote_anchor_name(tokens, idx, options, env, slf)
	let refid = id
	let n = Number(tokens[idx] + 1).toString()
	if (tokens[idx].meta.subId > 0) refid += `:${tokens[idx].meta.subId}`

	return `
	<sup class="footnote-ref">
	<a href="#fn${id}" id="fnref${refid}">
	<span aria-hidden="true">[${n}]</span>
	<span class="visually-hidden">Link to footnote ${n}</span>

mdengine.renderer.rules.footnote_anchor = (tokens, idx, options, env, slf) => {
	let id = slf.rules.footnote_anchor_name(tokens, idx, options, env, slf)
	let n = Number(tokens[idx] + 1).toString()
	if (tokens[idx].meta.subId > 0) id += `:${tokens[idx].meta.subId}`

	return `
	<a href="#fnref${id}" class="footnote-backref">
	<span aria-hidden="true">\u21a9\uFE0E</span>
	<span class="visually-hidden">Return to article via footnote ${n}</span>

module.exports = function (eleventyConfig) {
	eleventyConfig.setLibrary("md", mdengine);

The rel­e­vant stuff is in the mid­dle, wherein we use .renderer.rules to mess with the tags the foot­notes plu­gin wants to in­sert. Ideally, you’d want to be able to give these an ac­tual la­bel, es­pe­cially since [^cool-note-title] is valid syn­tax, but if there is an easy way to do that, it’s not some­thing I can rip right out of the plug­in’s own code. You’d think footnote_anchor_name or footnote_caption would do it, but nope.

I at least keep it kind of sane, by la­bel­ing each by the foot­note num­ber. So, us­ing this very page’s own foot­note as an ex­am­ple, Link to foot­note 1 we get

<!-- the ref tag -->
<sup class="footnote-ref">
	<a href="#fn-ten-percent-more-accessible-footnotes-1" id="fnref-ten-percent-more-accessible-footnotes-1">
		<span aria-hidden="true">[1]</span>
		<span class="visually-hidden">Link to footnote 1</span>

<!-- the footnote anchor -->
<a href="#fnref-ten-percent-more-accessible-footnotes-1" class="footnote-backref">
	<span aria-hidden="true">↩︎</span>
	<span class="visually-hidden">Return to article via footnote 1</span>

This is still not great; again, you’d ac­tu­ally want to be able to give a more cus­tomiz­able la­bel, and javascript is old sor­cery shit that fright­ens me so I can’t say I’d be able to do that. It is, at the very least, some­thing.

  1. This was part of a big­ger ar­ti­cle, but es­pe­cially since peo­ple don’t seem to have good pure-mark­down foot­notes in gen­eral it feels like I should’ve made it a sep­a­rate deal. Return to ar­ti­cle via foot­note 1 by nomiti ityool 2024
CC BY-SA 4.0 unless marked otherwise
made with Eleventy v2.0.1

rss feed lives here
if you use this for AI i hope my dogshit sentence structure poisons it