Skip to content

Add aria-level to toctree caption headings#14437

Open
Mirochill wants to merge 1 commit into
sphinx-doc:masterfrom
Mirochill:fix-14030-toctree-caption-aria-level
Open

Add aria-level to toctree caption headings#14437
Mirochill wants to merge 1 commit into
sphinx-doc:masterfrom
Mirochill:fix-14030-toctree-caption-aria-level

Conversation

@Mirochill
Copy link
Copy Markdown

@Mirochill Mirochill commented May 18, 2026

Summary

  • add an explicit aria-level=2 to toctree caption headings rendered with role=heading
  • keep the historical implicit heading level explicit so HTML validators accept the markup without changing the exposed outline
  • update the existing HTML expectation for translated toctree captions

Rationale

Sphinx has rendered toctree captions as <p role=heading> since #9358. WAI-ARIA requires heading roles to expose aria-level, and ARIA 1.1 defines the omitted value as level 2; making that level explicit preserves the existing semantics while resolving the validator error reported in #14030.

Fixes #14030.

Validation

  • Not run locally
  • relying on the repository's GitHub Actions / Read the Docs checks for remote validation

@Mirochill Mirochill force-pushed the fix-14030-toctree-caption-aria-level branch 2 times, most recently from be2142a to ac1bc09 Compare May 18, 2026 15:59
@Mirochill Mirochill force-pushed the fix-14030-toctree-caption-aria-level branch from ac1bc09 to baae5f0 Compare May 18, 2026 16:03
@Mirochill Mirochill marked this pull request as ready for review May 18, 2026 16:13
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.

HTML validation error due to missing aria-level for <p> submenu captions

1 participant