Accessible anchor permalinks

Eleventy uses markdown-it as its Markdown parser. So in order to enable deeplinking to the fragment identifiers of a section header you can use the markdown-it-anchor plugin. Version 8 saw some changes in reponse to a discussion to improve accessibility of these anchors on Github.

As I was updating from an earlier version, I ran into an issue. I had decided upon using the linkAfterHeader style of permalink which outputs the anchor as an adjacent sibling to the the heading. In times of grid-items and flex-items, that makes styling a little tricky: it would be nice to have a wrapper around it.

Both Nicolas Hoizey and Stephanie Eckles ran into the same issue, which they solved by employing a custom permalink function. I didn’t quite want to go that route, so I used eleventy transforms to post-process the HTML to insert the wrapper.

And that was going to be the subject of this post, until I figured I could ask Valérian Galliat, the maintainer of the project, if he thought adding a wrapper option would make sense. And he did.

Here’s the options object I pass to markdown-it-anchor

{
  permalink: markdownItAnchor.permalink.linkAfterHeader({
    style: 'visually-hidden',
    assistiveText: (title) => `Permalink to “${title}”`,
    visuallyHiddenClass: 'visually-hidden',
    class: 'header__permalink',
    wrapper: ['<div class="header">', '</div>'],
  }),
}

Well, that made short work of this post. Thank you, Val.

If you’re using Val’s plugin, consider buying him coffee. 🙌