Repository navigation
DocSearch result UX: anchor collisions and inconsistent lvl1 casing #1339
Description
Surfaced while auditing the Algolia DocSearch crawler config against the new docs structure in #1317. Two pre-existing docs-site bugs were masked by the old broken crawler config; both are visible in the DocSearch result modal now that hierarchy extraction works.
Anchor collisions on shared sub-section headings
Astro's markdown processor auto-generates kebab-case ids for every heading. The migration content rendered inside <details> (v1 breaking-changes) and <Prose> (lodash mapping) repeats sub-section headings across cards, producing duplicate id attributes on the same page:
| Page | Shared anchor | Records |
|---|---|---|
/migrate/v1 |
#runtime |
50 |
/migrate/v1 |
#typing |
56 |
/migrate/lodash |
#missing-input |
32 |
/migrate/lodash |
#normalized |
24 |
/migrate/lodash |
#simple-strings |
16 |
Searching v1 clone Runtime produces a hit pointing at /migrate/v1#runtime, but the browser scrolls to the first <h4 id="runtime"> in DOM order — a different function. Chrome 112+ and Safari 16+ also auto-open the surrounding <details> on hash navigation, so the user lands fully expanded inside the wrong card with no obvious clue why.
Proposed fix: strip auto-generated ids from h4/h5/h6 inside packages/docs/src/components/v1/function-card.astro and packages/docs/src/components/mapping-function-card.astro. Either a scoped rehype plugin or a heading-id remapper that prefixes with the parent function name. The lvl3 records in the search index then lose their precise breadcrumb but the URL collapses to the parent function's anchor — which already works correctly.
Inconsistent lvl1 casing
The category lvl1 field reads differently per page:
/docs— lowercase:array,object,function,guard/migrate/lodash— TitleCase:Array,Object/migrate/v1— TitleCase:Array,Object
Source: packages/docs/src/lib/functions/entries.ts:25 calls category.toLowerCase() when grouping; the mapping and v1 entries don't. Visually invisible on-site (the category <h2> is sr-only with no text-transform), but the DocSearch modal renders it as a breadcrumb — so users see array › filter on /docs and Array › clone on /migrate/v1.
Proposed fix: drop the .toLowerCase() and let @category JSDoc casing flow through. sortByCategories sorts on the raw category string and would pick up TitleCase ordering automatically.
Not urgent. Both are cosmetic-to-mid-tier UX bugs that lived under the old crawler config without anyone noticing, and neither is regressed by #1317.
Activity