ability to add custom attributes based on headings to the links

[schardev]

Initial checklist

• I read the support docs
• I read the contributing guide
• I agree to follow the code of conduct
• I searched issues and couldn’t find anything (or linked relevant results below)

Problem

It would be great if the plugin allow us to insert labels based on the heading text like this:

<h2 id="motive">
  Motive
    <a href="#motive" class="anchor-link" aria-label="motive">
       <span class="icon icon-link"></span>
    </a>
</h2>

Solution

Maybe accept a function and expose the heading node so that we can freely modify/add extra dynamic properties like these, just like how it currently works for options.content option would be sufficient I believe

for example:

import {rehype} from 'rehype'
import rehypeAutolinkHeadings from 'rehype-autolink-headings'
import {toString} from 'hast-util-to-string'

main()

async function main() {
  const file = await rehype()
    .data('settings', {fragment: true})
    .use(rehypeAutolinkHeadings, {
      behavior: 'append',
      properties(node) {
          return {'aria-label': toString(node), tabIndex: -1}
      }
    })
    .process('<h1 id="xxx">Hello World</h1>')

  console.log(String(file))
}

should log:

<h1 id="xxx">Hello World<a aria-label="Hello World" tabindex="-1" href="#xxx"><span class="icon icon-link"></span></a></h1>

Alternatives

or ... the individual property keys takes a function instead with a heading node? Like this:

import {rehype} from 'rehype'
import rehypeAutolinkHeadings from 'rehype-autolink-headings'
import {toString} from 'hast-util-to-string'

main()

async function main() {
  const file = await rehype()
    .data('settings', {fragment: true})
    .use(rehypeAutolinkHeadings, {
      behavior: 'append',
      properties: {'aria-label': (headingNode) => toString(headingNode), tabIndex: -1}
    })
    .process('<h1 id="xxx">Hello World</h1>')

  console.log(String(file))
}

I don't know the performance implication of this, but this doesn't feel a good enough alternative

[Murderlon]

You're problem may be an XY problem. Instead of having a link with an icon and using aria-label to still assign a value, I would do it the other way around.

<h2 id="motive">
  Motive
    <a href="#motive" class="anchor-link">
       <span aria-hidden class="icon icon-link"></span>
       <span class="visually-hidden">Motive</span>
    </a>
</h2>

Wouldn't that also solve your problem?

[schardev]

Technically that should work, yes. The reason why I wanted to do it that way is because I've seen popular sites like Material UI and Vite.js add aria-labels directly to their link tag instead, which looked clean tbh as it avoids adding an extra DOM node just to please Lighthouse or accessibility guidelines.

Your solution works for me for now, but let's say I want to add some other custom attribute (data-* attributes possibly) that needs the heading string. Then what? Though, to be fair, I can't come up with any use case that requires that behavior right now.

[wooorm]

a) You can pass a function, it is passed the heading? 🤔 Or do you mean that options.properties cannot be a function yet?
b) I don’t think this passes accessibility guidelines: screenreaders will read “motive motive”. If accessibility is important (it probably should!) I’d say label it as Link to this heading (“Motive”) maybe?

[schardev]

@wooorm

a) I was just saying it'd be great if options.properties can take a function that has access to the heading node being autolinked so that I can add dynamic attributes based on the heading text

b) yeah. This seems better. I think I can do that with options.content if I have to implement it like how @Murderlon said. I was just asking if there's a way to do it like how these other sites have done it.

[wooorm]

I’m up for a PR to add function support I think, I don’t see downsides?

[Murderlon]

Makes sense to have it as a function, also aligns better with the content option.

[wooorm]

it’s in 7.0.0!