Skip to content

Suffix the ids in the cloned body TOC - #14853

Draft
cwickham wants to merge 1 commit into
feature/nav-landmark-labelsfrom
fix/14844-double-toc-duplicate-ids
Draft

Suffix the ids in the cloned body TOC#14853
cwickham wants to merge 1 commit into
feature/nav-landmark-labelsfrom
fix/14844-double-toc-duplicate-ids

Conversation

@cwickham

@cwickham cwickham commented Sep 4, 2026

Copy link
Copy Markdown
Member

Closes #14844.

Description

With toc-location: left-body or right-body, the useDoubleToc branch clones
the whole table-of-contents nav and renames only the nav itself, from TOC
to TOC-body. Every id inside the clone was copied as is. A page therefore
carried two elements for the toc-title heading, and two for each
toc-<section> link. The number of duplicates grows with the size of the TOC.

Ids must be unique in the tree (HTML Standard, the id attribute).
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 the
clone's aria-labelledby at the renamed heading:

<nav id="TOC" role="doc-toc" aria-labelledby="toc-title" class="toc-active">
  <h2 id="toc-title">Contents</h2>
  ...<a href="#section-1" id="toc-section-1">Section 1</a>

<nav id="TOC-body" role="doc-toc" aria-labelledby="toc-title-body">
  <h2 id="toc-title-body">Contents</h2>
  ...<a href="#section-1" id="toc-section-1-body">Section 1</a>

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 nav reads the link ids.
They come from Pandoc's TOC writer, and a search across src/ for "toc-",
#toc-$, and getElementById("toc finds no consumer in Quarto's JS, SCSS, or
Lua filters.

The originals stay on the sidebar copy, which is first in tree order. So
document.getElementById("toc-section-1") returned the sidebar element before
this 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):

If a navigation landmark has an identical set of links as another
navigation landmark on the page, use the same label for each navigation
landmark.

axe-core's landmark-unique still reports these two nav elements. That is a
best-practice rule, 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-body page:

rendered with duplicate ids duplicate-id-aria landmark-unique
main 4 inapplicable violation (moderate)
#14813 4 incomplete, critical violation (moderate)
this PR 0 passes violation (moderate)

duplicate-id-aria now passes rather than being inapplicable, because the
reference 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-title or toc-section-1.

Both pass. With the change to format-html-bootstrap.ts reverted,
left-body.qmd fails, so the assertions catch the fault they describe.

Also ran locally, all passing:

Checked by hand:

  • Both landmarks still report the name "Contents" in Chromium's accessibility
    tree, for nav#TOC and nav#TOC-body.
  • right-body behaves the same as left-body.
  • toc-title: "" produces no heading and no aria-labelledby. The guard holds,
    the link ids are still suffixed, and no id repeats.
  • toc-title: false fails YAML validation on the base branch too, so no TOC
    renders without a heading through metadata.

I did not run the full suite locally. CI covers it.

Checklist

I have (if applicable):

  • referenced the GitHub issue this PR closes
  • updated the appropriate changelog in the PR
  • ensured the present test suite passes
  • added new tests
  • created a separate documentation PR in Quarto's website repo and linked it to this PR

The ids are internal, and no documented option changes, so there is nothing to
document on quarto.org.

AI-assisted PR
  • AI tool used: Claude Code
  • Codebase grounding: local clone
  • Human review: I have reviewed, tested, and verified the AI-generated content before submitting.

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.
@posit-snyk-bot

posit-snyk-bot commented Sep 4, 2026

Copy link
Copy Markdown
Collaborator

Snyk checks have passed. No issues have been found so far.

Status Scan Engine Critical High Medium Low Total (0)
Open Source Security 0 0 0 0 0 issues
Licenses 0 0 0 0 0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants