Suffix the ids in the cloned body TOC - #14853
Draft
cwickham wants to merge 1 commit into
Draft
Conversation
With `toc-location: left-body` or `right-body`, `useDoubleToc` clones the whole TOC `nav` and renamed only the `nav` itself, from `TOC` to `TOC-body`. Every id inside the clone was copied as is, so the page carried two elements for the `toc-title` heading and for each `toc-<section>` link. Ids must be unique in the tree. The duplicates were inert until #14376 labelled the TOC landmark with `aria-labelledby="toc-title"`, which turned one of them into an ARIA reference: axe-core's `duplicate-id-aria` went from inapplicable to needs-review (critical) on these pages. Suffix every id the clone carries with `-body`, and repoint its `aria-labelledby` at the renamed heading. Nothing outside the nav references these ids, and the originals stay on the sidebar copy, so `getElementById` resolves exactly as it did before. Both landmarks keep the accessible name from the TOC title. That shared name is correct here: the APG asks for the same label on two navigation landmarks that hold an identical set of links, so axe's `landmark-unique` best-practice result stays and should not be fixed by renaming the labels.
Collaborator
✅ Snyk checks have passed. No issues have been found so far.
💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #14844.
Description
With
toc-location: left-bodyorright-body, theuseDoubleTocbranch clonesthe whole table-of-contents
navand renames only thenavitself, fromTOCto
TOC-body. Every id inside the clone was copied as is. A page thereforecarried two elements for the
toc-titleheading, and two for eachtoc-<section>link. The number of duplicates grows with the size of the TOC.Ids must be unique in the tree (HTML Standard, the
idattribute).The duplicates were inert until #14376 labelled the TOC landmark with
aria-labelledby="toc-title". That reference makes one of them load-bearing.This PR suffixes every id the clone carries with
-body, and repoints theclone's
aria-labelledbyat the renamed heading:Why every id, and not only the heading
The heading is the one id that ARIA references, so a minimal fix could rename
only that. I widened it because nothing outside the
navreads the link ids.They come from Pandoc's TOC writer, and a search across
src/for"toc-",#toc-$, andgetElementById("tocfinds no consumer in Quarto's JS, SCSS, orLua filters.
The originals stay on the sidebar copy, which is first in tree order. So
document.getElementById("toc-section-1")returned the sidebar element beforethis change and returns the same element after it. Third-party CSS or JS that
targets these ids sees no difference.
The accessible name does not change
Both landmarks keep the name from the TOC title. That shared name is the correct
outcome here, and it is what the ARIA Authoring Practices Guide asks for
(Landmark Regions, Step 3):
axe-core's
landmark-uniquestill reports these twonavelements. That is abest-practicerule, not WCAG, and this is the case the APG carves out. Do not"fix" it by giving the two TOCs different labels — that would make the page
worse for screen reader users. It belongs in an axe baseline.
Measured effect
axe-core 4.10.3, the version Quarto vendors, over a rendered
toc-location: left-bodypage:duplicate-id-arialandmark-uniquemainduplicate-id-arianow passes rather than being inapplicable, because thereference exists and resolves to one element.
Testing
Extended the two existing fixtures for this layout,
tests/docs/smoke-all/issues/3473-toc-side-body/{left-body,right-body}.qmd,with positive assertions for the suffixed ids and negative assertions that the
clone no longer carries
toc-titleortoc-section-1.Both pass. With the change to
format-html-bootstrap.tsreverted,left-body.qmdfails, so the assertions catch the fault they describe.Also ran locally, all passing:
3473-toc-side-body/{body,left,right}.qmd— the layouts that render one TOCare unaffected.
accessibility/toc-nav-label.qmd— the fixture Give every website and booknavlandmark a distinct, localizable label #14813 adds.Checked by hand:
tree, for
nav#TOCandnav#TOC-body.right-bodybehaves the same asleft-body.toc-title: ""produces no heading and noaria-labelledby. The guard holds,the link ids are still suffixed, and no id repeats.
toc-title: falsefails YAML validation on the base branch too, so no TOCrenders without a heading through metadata.
I did not run the full suite locally. CI covers it.
Checklist
I have (if applicable):
The ids are internal, and no documented option changes, so there is nothing to
document on quarto.org.
AI-assisted PR