Skip to content

Add autopermalink toggle feature for HTML rendering#2816

Open
blrichwine wants to merge 4 commits into
PreTeXtBook:masterfrom
blrichwine:add-autopermalink-toggle
Open

Add autopermalink toggle feature for HTML rendering#2816
blrichwine wants to merge 4 commits into
PreTeXtBook:masterfrom
blrichwine:add-autopermalink-toggle

Conversation

@blrichwine

@blrichwine blrichwine commented Apr 3, 2026

Copy link
Copy Markdown

Description

This PR adds a proof-of-concept toggle feature that allows readers to show and hide div.autopermalink elements in HTML output of a PreTeXt textbook.

Note: I attended the Zoom PreTeXt Dropin on Thursday 2026-04-02 and discussed the autopermalink toggle. Oscar and Chrissy mentioned I should create a PR so they can see the sample implementation and be reminded to consider the feature request. It was mentioned that the actual feature if implemented would likely be implemented differently and I am totally fine with that.

Motivation

Permalink icons are always presented to screen-reader users in the current output. We received feedback from screen reader users evaluating our use of PreTeXt. They reported that repeatedly hearing "Link: Copy heading and permalink for Paragraph" while reading a textbook is both distracting and annoying. These links also present numerous tab stops to keyboard only users that may not be interested in creating permalinks.

The fix we propose is to have permalinks links enabled only when needed, then the best of both worlds can be achieved.

Enabling the Feature

For this proof-of-concept, the feature is enabled on a per book basis. In the publisher file, add <permalink-button/> inside an <html> element:

  <publication>
    <html>
      <permalink-button/>
    </html>
  </publication>

Behavior

  • When enabled, div.autopermalink elements are hidden by default on page load
  • A button appears in the navbar that toggles permalink visibility
  • The button label and icon update to indicate what will happen when pressed:
    • "Enable Permalinks" with a link icon (link)— clicking will show permalinks
    • "Disable Permalinks" with a broken link icon (link_off) — clicking will hide permalinks
  • The reader's preference persists across page loads via localStorage
  • The feature is opt-in — existing books are unaffected unless the author enables it.
    • This is perhaps not the most user-forward means of implementing it, but is the choice made here to demo the feature.
    • This trade-off was made because no user settings / display preferences mechanism is available beyond what exists in the nav bar. I placed the permalink toggle button next to the other display preference button (light/dark mode toggle) and made it behave similar to how that button behaves.

Accessibility

  • The toggle permalinks button uses an aria-label attribute that updates to describe the action the button will perform, consistent with the pattern used by other PreTeXt navbar controls
  • display: none removes hidden permalinks from both the visual and accessibility tree
  • Permalinks are hidden via a CSS rule injected into before the page paints, preventing any flash of visible content

Other notes

  • Localized strings are currently only defined in en-US.xml. Other locales have not been provided. These will fallback to English automatically until translators add their own entries.
  • The ptx_default_settings JS object is how this code is passing the XSL settings to the new JS. Is ptx_default_settings the right pattern for passing XSL settings to the JS space, or is there a preferred alternative?
  • I initially had an aria-pressed attribute on the button, but feedback from a JAWS screen reader was that having both the changing button name and the aria-pressed state was confusing. The aria-pressed attribute was removed the JAWS user reported this was best.

Description of changes

  • xsl/publisher-variables.xsl:
    • Add $b-has-permalink-button variable reading $publication/html/permalink-button
  • xsl/pretext-html.xsl:
    • Add permalink-toggle-button named template
    • wire into primary-navigation-other-controls
    • emit ptx_default_settings script block
    • inject CSS to hide permalinks before JS runs
  • xsl/localizations/en-US.xml
    • Add permalink-enable and permalink-disable localization string IDs
  • js/pretext_add_on.js
    • Add initPermalinkToggle() and setPermalinkVisibility()
    • read localized labels from data- attributes

@blrichwine

blrichwine commented Apr 3, 2026

Copy link
Copy Markdown
Author

Note: I have a sample implementation of the feature in the examples/minimal book hosted here: https://brichwin.pages.iu.edu/min/minimal.html

@rbeezer

rbeezer commented Apr 3, 2026

Copy link
Copy Markdown
Collaborator

Thanks, @brichwin. I would be annoyed stopping and hearing all those permalinks! So it would be good to have more control over them.

We have been talking about a general user preferences/readability menu (and had a trial one once a while back). Maybe this can help move that forward. Feels like that is where it belongs.

@davidfarmer

davidfarmer commented Apr 3, 2026 via email

Copy link
Copy Markdown
Contributor

@blrichwine

blrichwine commented Apr 3, 2026 •
edited
Loading

Copy link
Copy Markdown
Author
  1. A non-sighted/keyboard navigating reader is probably going to use the "skip to main content" link. Perhaps following that link turns off the permalinks?

The student screen-reader users I've worked with don't use the skip to content links on sites. They mainly use headings to get to the main content by pressing the 'H' quick nav key till they get there.

Also, you really don't want simple navigation of a site to change user settings. It wouldn't be very transparent. And they might actually want to use the permalink feature. We have several instructors that use screen-readers...

@rbeezer

rbeezer commented Jun 1, 2026

Copy link
Copy Markdown
Collaborator

I don't want anybody to think this PR has been orphaned. But I'm not sure where we are on it? I asked @oscarlevin to run with it, since it seems to be mostly JS and CSS and he could guide this to completion, but we have comments from @davidfarmer that maybe have not been addressed? Anyway, not sure whose court the ball is in? And if it is mine, let me know what needs my attention.

@oscarlevin

oscarlevin commented Jun 1, 2026 via email

Copy link
Copy Markdown
Member

@rbeezer rbeezer mentioned this pull request Jun 22, 2026
Closed
@rbeezer

rbeezer commented Jun 22, 2026

Copy link
Copy Markdown
Collaborator

See in-progess (general) work on #2951.

@davidfarmer said:

So I would like permalinks on by default

I agree. See discussion on #2951.

@brichwin

brichwin commented Jun 22, 2026

Copy link
Copy Markdown

Is the on by default an option that can be set by the publisher/author? For example, our faculty would prefer the permalinks off by default since students with screen readers would otherwise have to discover how to turn them off and the faculty are aware enough to turn them on when they need them.

@ascholerChemeketa

ascholerChemeketa commented Jun 22, 2026

Copy link
Copy Markdown
Contributor

When we have a report from screen reader uses that permalinks are distracting, we should take it seriously. Even in my limited use of a screen reader for testing pages, I find they drive me nuts. I can only imagine trying to read the content and having them pop up.

I wasn't aware of this (or had forgotten???) when I implemented #2951. It takes the approach of making them invisible to screen readers by default with a switch to turn them on. The thinking was much what @brichwin just mentioned - instructors will likely know/figure out how to turn them on, but students trying to read won't have to fight through them until they realize there is a setting to turn them off.

I think it makes more sense as a reader setting than a book level one, and now (well, in-flight) we have a place for those.

@rbeezer

rbeezer commented Jun 22, 2026

Copy link
Copy Markdown
Collaborator

I do not want to sound insensitive, but this is a case where a valuable feature for the majority of readers should be apparent out-of-the-box. I am aware of how intrusive they are with a screen reader.

Can we not toggle "screen reader visibility" somehow? Default is visible for sighted readers and "anannounced" for those with screen readers? Maybe we have two items on the new menu?

@rbeezer

rbeezer commented Jun 22, 2026

Copy link
Copy Markdown
Collaborator

s/anannounced/unannounced/ ;-)

@brichwin

brichwin commented Jun 22, 2026

Copy link
Copy Markdown

FYI - There are other users who would need them turned completely off that aren't screen reader users. For example, try accessing links using voice control in a page with a lot of content. Voice control has trouble handing pages with a lot of links. For example, try saying "Show links" on a long page with literally 100's of permalinks.

I'd keep it simple. Have them on or off. I wouldn't have them simply not announced for screen reader users as normally a link with aria-hidden is still available to voice control users. Also, there are other TTS readers for the print impaired audience (sighted users with dyslexia, ESL, etc.) which don't always honor aria-hidden.

@ascholerChemeketa

ascholerChemeketa commented Jun 22, 2026

Copy link
Copy Markdown
Contributor

Live sample of implementation as reader options: https://computerscience.chemeketa.edu/ascholer/pretext-test/reader-opts/section-fundamental-theorem.html

@rbeezer "announced" is a major part of the awful part. Your average student never makes use of them and thus they have limited value for that user. And students are the vast majority of users (and of non-power users). The default out of the box should be as useful as possible. If a feature provides little value to that median user, and causes active issues, it should be opt in.

@blrichwine I think part of the answer is to reimplement them as buttons or at least give them that aria-role. "Links go somewhere and buttons do something" The autopermalinks do something. That would help with the link based navigation, right?

@brichwin

brichwin commented Jun 22, 2026 •
edited
Loading

Copy link
Copy Markdown

@blrichwine I think part of the answer is to reimplement them as buttons or at least give them that aria-role. "Links go somewhere and buttons do something" The autopermalinks do something. That would help with the link based navigation, right?

Probably. I'd have to go back and look at the UI chrome around the document. The document wouldn't typically have buttons, so if a student is trying to activate a link in the document, they would be asking to activate links. Having the links list not cluttered by the permalinks would be helpful. The next/previous navigation "buttons" are coded as links, so I think it would be fine.

Of course, if they are off by default regardless if links or buttons then it is a non-issue.

@davidfarmer

davidfarmer commented Jun 22, 2026

Copy link
Copy Markdown
Contributor

Here are two apparently conflicting good points:

  1. Permalinks should be on by default, because most publishers will not know about those.
  2. Permalinks are not good for screen readers.

Is putting aria-hidden="true" on permalinks sufficient to satisfy both?
(Or some other way to hide them from screen readers.)

@brichwin

brichwin commented Jun 22, 2026

Copy link
Copy Markdown

Here are two apparently conflicting good points:

  1. Permalinks should be on by default, because most publishers will not know about those.
  2. Permalinks are not good for screen readers.

Is putting aria-hidden="true" on permalinks sufficient to satisfy both? (Or some other way to hide them from screen readers.)

It's tricky:

  • They would need to be keyboard accessible to meet WCAG requirements. Having a tab stop that is also aria-hidden is a problem for screen readers.
  • There are many TTS readers for sighted users wanting text-to-speech that ignore (don't honor) aria-hidden
  • The last time I checked (it's been over a year though) voice control still lists links/buttons that have aria-hidden on them

@ascholerChemeketa

ascholerChemeketa commented Jun 22, 2026

Copy link
Copy Markdown
Contributor

That is what 2591 does - it defaults to aria-hidden="true" and tab-indes="-1" on them. That makes them invisible to screen readers and keyboard navigation. Then the reader setting can reenable them by removing those attributes. They are always visible/interactive when using a pointer.

@brichwin - what TTS should we check against? I think making them buttons would help in that they would not count as links. Even if the tool ignored aria-hidden, it would at least not announce them as links on the page when the user asked to activate the links.

@brichwin

brichwin commented Jun 22, 2026 •
edited
Loading

Copy link
Copy Markdown

Both Voice Control in macOS and Voice Access in Windows 11 are popular.

macOS Voice Control:

Windows 11 Voice Access

@ascholerChemeketa

ascholerChemeketa commented Jun 22, 2026

Copy link
Copy Markdown
Contributor

I don't have access to a mac, but with Win11 Voice Access, and 2591 in place the items are not revealed by default with "Show numbers". When I use the reader option to "expose permalinks" and then do "Show numbers" with Voice Access, I do see the permalinks as numbered items.

btw just fixed the sample at https://computerscience.chemeketa.edu/ascholer/pretext-test/reader-opts/section-fundamental-theorem.html - some of the JS was out of date.

@rbeezer

rbeezer commented Jun 22, 2026

Copy link
Copy Markdown
Collaborator

Let's make sure we are doing the right thing versus accomodating tools that are deficient. The tools can catch up.

@brichwin

brichwin commented Jun 22, 2026

Copy link
Copy Markdown

I don't have access to a mac, but with Win11 Voice Access, and 2591 in place the items are not revealed by default with "Show numbers". When I use the reader option to "expose permalinks" and then do "Show numbers" with Voice Access, I do see the permalinks as numbered items.

btw just fixed the sample at https://computerscience.chemeketa.edu/ascholer/pretext-test/reader-opts/section-fundamental-theorem.html - some of the JS was out of date.

I had my colleague Mary Stores test reading https://computerscience.chemeketa.edu/ascholer/pretext-test/reader-opts/section-fundamental-theorem.html using the JAWS screen reader. She was able to read the main content without hearing the permalinks. Then I asked her to see if she could turn on the permalinks and use them (without telling her how). She first tried the embed control but then found the reading options and was able to successfully turn them on and then use them.

@rbeezer

rbeezer commented Jun 22, 2026

Copy link
Copy Markdown
Collaborator

I had my colleague Mary Stores test reading

Fabulous - thanks for the testing!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@oscarlevin oscarlevin

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

6 participants

@blrichwine @rbeezer @davidfarmer @oscarlevin @brichwin @ascholerChemeketa