Links should either be labeled or removed from tabbing about remark-autolink-headings

[wooorm]

Alright, pushed a couple of things so all of the above ideas are now possible!

For your last example, these options (pseudocode) should do the trick:

var toString = require('mdast-util-to-string')
var h = require('hastscript')

var options = {
  behavior: 'after',
  group: h('div'),
  content: function (node) {
    return [
      h('span.visually-hidden', 'Read the "', toString(node), '" section'),
      h('span.icon.icon-link', {ariaHidden: true})
    ]
  }
}

[chaance]

Thanks for the reference @wooorm, I was struggling to find good examples in the wild. His approach is also good, as the link and the heading will both be announced.

<div>
  <h2 id="what-exactly-is-a-portal" tabindex="-1">What exactly is a portal?</h2>
  <a href="#what-exactly-is-a-portal">
    <span class="visually-hidden">Read the "What exactly is a portal?" section</span>
    <span class="icon icon-link" aria-hidden="true"></span>
  </a>
</div>

[wooorm]

Heya! I remember a while back we talked about accessibility and weren't totally sure what the preferred method would be, I couldn't find any articles on this then, do you know of any?

Regarding your first solution, that is already an option with the 'wrap' behavior, right?

I'm up for changing the default to wrap, but would still like to make append and prepend accessible as well, any suggestions for those?

[chaance]

I'll look around – I'm not 100% sure that this is covered in spec, but I do know that there is an axe testing rule that catches things like this for the reasons I specified: https://dequeuniversity.com/rules/axe/3.3/aria-hidden-focus

A related SO exchange: https://stackoverflow.com/a/52208194

Basically, if you want to hide the links, it's best to remove their tab order. That underlying decision though may be subjective, and so I'd argue that folks using SRs and keyboards to navigate should be able to access the links for the same reasons anyone else might need them. Didn't know about the wrap option, which is great! In that case I'd advocate for using aria-labelledby as the default.

Others may disagree. I forgot that, just reading through the content, a header will be read twice if you remove aria-hidden, but I'm unsure how either NVDA or JAWS might deal with having both a label and a hidden attribute. But at least with VoiceOver, this works great:

<h2 id="what-exactly-is-a-portal">
  <a href="#what-exactly-is-a-portal" aria-labelledby="what-exactly-is-a-portal" aria-hidden="true">
    <span class="icon icon-link"></span>
  </a>What exactly is a portal?
</h2>

I don't know of any articles unfortunately. Perhaps I should write one! Here is a relevant bit of the spec on how this affects SR users. https://www.w3.org/TR/WCAG20-TECHS/ARIA7.html

[chaance]

An even better solution suggested by @smhigley would be to pull the link out of the heading tag altogether. If you just need the heading for positioning purposes, this should work better than trying to hide the link!

<div> <!-- outer div for positioning the link -->
  <a href="#what-exactly-is-a-portal" aria-labelledby="what-exactly-is-a-portal">
    <span class="icon icon-link" aria-hidden="true"></span>
  </a>
  <h2 id="what-exactly-is-a-portal">What exactly is a portal?</h2>
</div>

[wooorm]

https://twitter.com/wooorm/status/1194902349610921984

[wooorm]

I love this, but the downside is that it wouldnt be a good option for a default, because of the English prefix and suffix 🤔