Skip to content

Add autopermalink toggle feature for HTML rendering#2816

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

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

Conversation

@blrichwine
Copy link
Copy Markdown

@blrichwine blrichwine commented Apr 3, 2026

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
Copy link
Copy Markdown
Author

blrichwine commented Apr 3, 2026

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
Copy link
Copy Markdown
Collaborator

rbeezer commented Apr 3, 2026

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
Copy link
Copy Markdown
Contributor

davidfarmer commented Apr 3, 2026 via email

@blrichwine
Copy link
Copy Markdown
Author

blrichwine commented Apr 3, 2026 •
edited
Loading

  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...

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

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@blrichwine @rbeezer @davidfarmer @brichwin