docs site: 172 of 403 doc pages get a breadcrumb that skips its section — `meta.json` listing `"index"` detaches the folder index

[os-zhuang]

One-liner

17 of the 35 meta.json files under content/docs list "index" in their pages array. Fumadocs only attaches a folder's index.mdx as that folder's tree index node when it is not listed, so those folders reach every tree consumer with a title and no URL — and 172 of 403 doc pages ship a breadcrumb that skips its section.

Measured, not inferred

Against a local production build (next build && next start) of origin/main + PR for #12240, reading rendered HTML:

docs URLs in sitemap: 403
complete trails: 231
short trails: 172
short trails by top-level folder:
 ai 8 · api 11 · automation 9 · capabilities 10 · concepts 5 · data-modeling 17
 deployment 11 · getting-started 8 · kernel 22 · permissions 20 · plugins 4
 protocol 24 · releases 8 · ui 15

A "complete" trail is one with a crumb for every path segment above the page. Every short trail sits under a folder whose meta.json lists "index"; every complete one under a folder that does not.

Side by side, from the emitted BreadcrumbList:

/docs/data-modeling/objects ObjectStack > Documentation > Object Metadata
/docs/protocol/objectql/query-syntax ObjectStack > Documentation > Data Protocol(/docs/protocol/objectql) > Query Syntax

content/docs/data-modeling/meta.json lists "index". content/docs/protocol/objectql/meta.json does not.

Causal confirmation (ablation)

Deleted the single line "index", from content/docs/data-modeling/meta.json, rebuilt, re-read the rendered page, then restored the file (git checkout HEAD -- …; git diff HEAD empty, blob hash back to the HEAD blob):

before: /docs/data-modeling/objects -> ObjectStack > Documentation > Object Metadata (3 crumbs)
after: /docs/data-modeling/objects -> ObjectStack > Documentation > Data Modeling(/docs/data-modeling) > Object Metadata (4)
control: /docs/ai/agents -> ObjectStack > Documentation > AI Agents (3, unchanged)

The mechanism is fumadocs-core's getBreadcrumbItems() (dist/breadcrumb.js), which links a folder crumb to item.index?.url. With "index" listed, folder.index is undefined, so the crumb has a name and no url.

Why it matters beyond cosmetics

• The folder index page is real: /docs/data-modeling answers 200, is in the sitemap, and carries a canonical and an OG card. The trail just cannot point at it.
• Google requires item on every BreadcrumbList entry except the last, so the JSON-LD emitted by docs site: no structured data (JSON-LD) anywhere #12240 drops the un-linkable ancestor rather than emitting a name-only crumb. 172 pages therefore advertise a two-level site structure they do not have.
• ⛔ It was deliberately not worked around in the consumer. Reconstructing the URL from the slug in app/[lang]/docs/[[...slug]]/page.tsx would hide this permanently. When this lands, those trails complete with no code change.

Not what I first assumed

I hypothesised these 17 index pages were also orphaned from navigation. False — crawling all 408 sitemap URLs for inbound hrefs finds only 4 orphans, none of them folder indexes. That is filed separately.

Fix

Remove "index" from the pages array in the 17 meta.json files that list it. index.mdx is picked up as the folder index automatically; listing it is what suppresses that.

⚠️ It also changes the sidebar (the ablated build gained a href="/docs/data-modeling" the control build did not have), so this is a navigation change and wants a look at the rendered sidebar, not just the JSON-LD.

Source

Found while implementing #12240 (JSON-LD / BreadcrumbList) — the PM's assumption for that card was that source.pageTree carries a clean ancestor chain. It carries the chain; half of it is unlinkable.

[os-trump]

Triage: lands in content/docs/** meta.json files (17 of them) — domain:devx, pm:queue, type Bug (172 of 403 pages emit a BreadcrumbList that skips a real, linkable ancestor), labels matched to sibling #12353 from the same sweep. Docs-site family: adjacent to epic #12243's SEO surface but filed as an independent defect card, same disposition as #12353; the devx/docs seat and the epic PM should fold-or-serial explicitly if both touch the same meta.json files in one window. Dispatch note: the card's own ⚠️ is load-bearing — removing "index" also changes the rendered sidebar, so acceptance needs a look at the sidebar, not only the JSON-LD; and the fix must stay producer-side (⛔ no consumer-side URL reconstruction in page.tsx, per the card's own fence).

---

Generated by Claude Code