Semantic changes proposed to several blocks and one inline element#1
Open
briandominick wants to merge 4 commits into
Open
Semantic changes proposed to several blocks and one inline element#1briandominick wants to merge 4 commits into
briandominick wants to merge 4 commits into
Conversation
A bare a.footnote-ref link is not announced as a footnote reference by most screen readers and renders inline with body text instead of as a superscript. Wrapping it in <sup> (with .footnote-ref class) restores both the visual and semantic cue without touching the link's own attributes/role. This is a BREAKING CHANGE for applications that expect a.footnote-ref, which is nolonger generated by the backend.
The block_with_title method rendered every block's optional title as an <h6>, regardless of where the block actually sits in the document's real section hierarchy. That's misleading to screen reader users navigating by heading level, and wrong whenever a titled block (e.g., a sidebar, admonition) ends up nested in an h2 or an h4. Now renders the title as a <p class="block-title" role="heading"> instead, linked to its containing block via aria-labelledby/id (generate_title_id). Adds role="heading" without aria-level to keeps it discoverable as a heading landmark without asserting a level that isn't real. Applies to every block type that goes through block_with_title (dlist, olist, ulist, quote, verse, literal, open-block) plus paragraph and sidebar, which built their title markup by hand. This is a BREAKING CHANGE for titled block elements. Admonitions are unaffected but are similarly modified in a subsequent change.
Per jirutka#26: an abstract is a summary written by the document's own author, not quoted material from someone else, so wrapping it in <blockquote> misrepresents it semantically (and to assistive tech that announces blockquotes as quotations). Render it as an untitled section with role="doc-abstract" (per the DPUB-ARIA module) and aria-label="Abstract" when there's no title, or aria-labelledby pointing at the block-title <p> when there is one -- consistent with how every other titled block is now labelled.
Inspired by but surpassing in scope jirutka#20, restructure the admonition's internal markup: - Replace the h6.block-title + span.title-label with a div.gutter holding the icon and the type label (Note, Tip, ...) separate from any user-supplied title, and a div.content holding the optional title and the body. Previously the type label and the title were awkwardly crammed into the same h6, and an untitled admonition just got a "label-only" h6 as a fake title. - The optional title, when present, is now a p.block-title (role=heading) inside .content, consistent with every other block type after the block-title h6 removal, linked via aria-labelledby on the outer aside/section. - span.icon is empty (decorative, filled in by CSS) and marked aria-hidden=true so assistive tech doesn't announce a blank node.
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
1 participant
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.
This is a demonstrative PR to show the substantive changes I propose to the html5s backend. It tries to stay as true as possible to the style and principles of the prime repo.