fix(a11y): stop docset grids skipping a heading level - #12594
Merged
mergify[bot] merged 2 commits intoSep 3, 2026
Merged
Conversation
Member
Author
|
This pull request is part of a Mergify stack:
|
This was referenced Aug 28, 2026
Contributor
Merge Protections🟢 All 7 merge protections satisfied — ready to merge. Show 7 satisfied protections🟢 ⛓️ Depends-On RequirementsRequirement based on the presence of
🟢 🤖 Continuous Integration
🟢 👀 Review Requirements
🟢 Enforce conventional commitMake sure that we follow https://www.conventionalcommits.org/en/v1.0.0/
🟢 🔎 Reviews
🟢 📕 PR description
🟢 🚦 Auto-queueWhen all merge protections are satisfied, this pull request will be queued automatically. |
There was a problem hiding this comment.
Pull request overview
Adjusts Docset card title markup to preserve a correct heading hierarchy in docset grids, improving the document outline for screen readers and other tooling.
Changes:
- Default
Docsetcard titles toh3(instead ofh4) and make the heading level configurable via aheadingLevelprop. - Set
headingLevel={4}for the CI Insights “Components” grid, since it is nested under an###heading.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| src/content/docs/ci-insights.mdx | Sets headingLevel={4} for the “Components” grid docset cards to avoid outline/structure issues under an ### heading. |
| src/components/DocsetGrid/Docset.astro | Introduces configurable heading level for card titles and updates styling to support both h3 and h4. |
Suppressed comments (2)
src/components/DocsetGrid/Docset.astro:33
- The card title is rendered as an h3/h4, but it contains a wrapper for the icon. Headings should only contain phrasing content; a block-levelinside a heading is invalid HTML and can confuse accessibility tooling. Use a (or other phrasing element) for the icon wrapper instead.
This issue also appears on line 34 of the same file.
{productIconName && (
<div class="docset-icon" data-product={productKey}>
<ProductIcon name={productIconName} />
</div>
)}
src/components/DocsetGrid/Docset.astro:38
- The h3/h4 heading contains a wrapper for the lucide/simple-icons icon. Ainside a heading is invalid HTML (headings should contain phrasing content only). Use a wrapper (and keep the same class/data attributes) to preserve styling while keeping markup valid.
{!productIconName && icon && (
<div class="docset-icon" data-product={productKey}>
<Icon name={icon} />
</div>
)}
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
jd
force-pushed
the
devs/jd/agentic-readiness/stop-docset-grids-skipping-heading-level--e01f4c2b
branch
from
August 28, 2026 14:37
4244760 to
76b1d20
Compare
Member
Author
Revision history
|
`getOgImageUrl` strips the leading and trailing slashes off the pathname to build the image filename. For the homepage that pathname is `/`, so stripping left an empty string and the lookup missed — every docs page had an OpenGraph image and the homepage shipped `<meta property="og:image">` with no content. The homepage's collection id is `index`, which is what `getStaticPaths` names its image, so fall back to that when the slug comes out empty. Covered by a regression test that fails against the old expression. The generated-image set comes from the content collection and needs the Astro build pipeline, so the test stubs it and exercises the derivation, which is the half that was wrong. Change-Id: Ifb9a23ea2caa20d28489a4f21363d85ed5e3342c
Docset cards rendered their title as `h4`. Almost every grid sits directly under an `##`, so the outline jumped h2 to h4 — including on the homepage, whose whole body is the "Products" grid. Screen readers and anything parsing the document outline read that as a missing level. Default the card heading to `h3` and make it a prop, because one grid does belong at h4: the "Components" grid in `ci-insights.mdx` is nested under an `### Components`, where h3 would make the cards siblings of their own section heading instead of children. Change-Id: Ie01f4c2b03f1f2b7f798ae89b056135a5b00800e
jd
force-pushed
the
devs/jd/agentic-readiness/stop-docset-grids-skipping-heading-level--e01f4c2b
branch
from
August 28, 2026 15:09
76b1d20 to
0ac1500
Compare
Base automatically changed from
devs/jd/agentic-readiness/restore-homepage-opengraph-image--fb9a23ea
to
main
September 1, 2026 08:55
AlexandreGaubert
approved these changes
Sep 1, 2026
remyduthu
approved these changes
Sep 3, 2026
Contributor
Merge Queue Status
This pull request spent 3 minutes 45 seconds in the queue, including 2 minutes 59 seconds running CI. Required conditions to merge
|
65 tasks
mergify
Bot
deleted the
devs/jd/agentic-readiness/stop-docset-grids-skipping-heading-level--e01f4c2b
branch
September 3, 2026 07:47
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.
Docset cards rendered their title as
h4. Almost every grid sits directlyunder an
##, so the outline jumped h2 to h4 — including on the homepage,whose whole body is the "Products" grid. Screen readers and anything parsing
the document outline read that as a missing level.
Default the card heading to
h3and make it a prop, because one grid doesbelong at h4: the "Components" grid in
ci-insights.mdxis nested under an### Components, where h3 would make the cards siblings of their own sectionheading instead of children.
Depends-On: #12593