Permalinks and accessibility

[Oscar Levin]

I'm working on a refactor of permalinks for pretext documents, and coincidentally an author pointed out how annoying it is to have their screen reader announce "link link" between every paragraph as it passes over the permalinks.

Should we put `aria-hidden="true"` on all permalinks?  I don't know if this would make them non-selectable, which might be good or bad, I don't know.  

Oscar.

[David Austin]

I've noticed this behavior and find it annoying as well.  So I would support this proposal provided the links are still selectable (what would be the point otherwise?), which I think they should be.

David

--
You received this message because you are subscribed to the Google Groups "PreTeXt accessibility" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pretext-a11y...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/pretext-a11y/4050c0cf-4a48-4167-9b84-6e6b911a4829n%40googlegroups.com.

[Oscar Levin]

Apparently using `aria-hidden="true"` removes the element from the accessible dom completely (like doing a `display: none` for visual elements).  As such, they cannot be navigated to by a keyboard (maybe TAB will let a user select the link, but an unsighted user would not know what they are).  So you could click them with a mouse, but not with a keyboard.  I'm very conflicted.  All the guides I've seen online say you should not hide these, but of course we have so many extra compared to most sites.

[Oscar Levin]

Updates!

Andrew fixed the permalinks so the speech at least says what they are.  So that's an improvement.

From a discussion on a Zulip community, Dave Kung reported this from his accessibility specialist:  The permalinks create a lot of semantic noise and make navigating with a keyboard more onerous. They demoed a script that ads a button to the top of the PreText page to toggle the permalinks on and off.

I think I'll start a new thread exploring this idea.

[David W. Farmer]

What if the "skip to main content" link also hid those permalinks?

> https://groups.google.com/d/msgid/pretext-a11y/e1fc0add-3b2c-4c69-8812-c8d2bc5eb7c4n%40googlegroups.com.
>
>

[David W. Farmer]

By "toggle the permalinks on and off" I understood (possibly incorrectly)
that the permalinks would be there, or not.

But I think you are headed toward: the links are always there,
but by default hidden from keyboard navigation.

On Fri, 1 Aug 2025, Oscar Levin wrote:

> I think we would want to be explicit about how to turn *on* the permalink speech in case an unsighted user wanted to find and
> use the links.  Most of the time, this could be off completely.

> https://groups.google.com/d/msgid/pretext-a11y/a2da29f5-4458-ff2c-8fbe-ebfad6b13653%40aimath.org.
>
>
>

[Alex Jordan]

A variant to consider.

• When the page first loads, permalinks are all there as now, but with aria-hidden="true". 
• There is a new link button alongside the other buttons (search, calculator, embed this page, toggle dark mode). Clicking this button toggles aria-hidden="true" and also changes CSS so that the individual link icons all become visible (but perhaps faded until hover, touch, or click).

But I would go a bit further. With this (as well as the status quo) you can still tab to permalinks at any time. Because the permalinks come later in the DOM than the thing they link to, tabbing is visually jerky. Like if there is a tall paragraph with several tabbable waypoints, you tab through those waypoints and then at the end, are brought all the way back to the top where that paragraph's permalink icon is.

So I would add that when the page loads, all permalinks have tabindex="0". And the button that toggles aria-hidden="true" on all of the permalinks would also toggle tabindex="0" and make the permalinks become tabbable.

Lastly, consider the experience of the blind user who wanted to use a permalink. They went up to the top nav and used a button to grant access to permalinks. Then they went and got the one they wanted. Most of the time, they don't need permalinks to remain accessible at this point. So upon using a permalink, everything reverts to aria-hidden="true" and tabindex="0", as well as the CSS reverting.

[Oscar Levin]

I think we would want to be explicit about how to turn *on* the permalink speech in case an unsighted user wanted to find and use the links.  Most of the time, this could be off completely.

On Fri, Aug 1, 2025 at 4:44 AM David W. Farmer <far...@aimath.org> wrote:

To view this discussion visit https://groups.google.com/d/msgid/pretext-a11y/a2da29f5-4458-ff2c-8fbe-ebfad6b13653%40aimath.org.

[Oscar Levin]

They would always be there, but they would get aria-hidden.