From 1a5ba4fa41cfcf1074ca7ea92d881198650df87f Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 31 Aug 2026 07:35:53 +0000 Subject: [PATCH] =?UTF-8?q?docs(nav):=20stop=20listing=20"index"=20in=20me?= =?UTF-8?q?ta.json=20pages=20=E2=80=94=20it=20detaches=20the=20folder=20in?= =?UTF-8?q?dex=20(#12352)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fumadocs attaches a folder's index.mdx as that folder's tree `index` node only when the folder's meta.json does NOT list "index" in `pages`. Listing it makes the page an ordinary child and leaves the folder node with a name and no url, which degrades both surfaces built from that node: `getBreadcrumbItems()` drops the un-linkable ancestor, and the sidebar renders an inert `SidebarFolderTrigger` instead of a `SidebarFolderLink`. Removes "index" from 16 of the 17 meta.json files that listed it. content/docs/releases/ is fenced by AGENTS.md and is left untouched. Measured on the real fumadocs-core 16.14.4 loader over content/docs: short breadcrumb trails 172 -> 8 (the 8 are all under /docs/releases), and the sidebar delta is exactly 16 folder headers TRIGGER -> LINK plus 16 index children leaving the child list, with no other entry moved. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01Pk26oZ12t5N1hwGW1m1MgC --- .../docs-meta-index-detaches-folder-index.md | 41 +++++++++++++++++++ .../docs/app/[lang]/docs/[[...slug]]/page.tsx | 30 +++++++------- content/docs/ai/meta.json | 1 - content/docs/api/meta.json | 1 - content/docs/automation/meta.json | 1 - content/docs/capabilities/meta.json | 1 - content/docs/concepts/meta.json | 1 - content/docs/data-modeling/meta.json | 1 - content/docs/deployment/meta.json | 1 - content/docs/getting-started/meta.json | 1 - content/docs/kernel/contracts/meta.json | 2 +- content/docs/kernel/meta.json | 1 - .../docs/kernel/runtime-services/meta.json | 1 - content/docs/permissions/meta.json | 1 - content/docs/plugins/meta.json | 1 - content/docs/protocol/kernel/meta.json | 1 - content/docs/protocol/meta.json | 1 - content/docs/ui/meta.json | 1 - 18 files changed, 56 insertions(+), 32 deletions(-) create mode 100644 .changeset/docs-meta-index-detaches-folder-index.md diff --git a/.changeset/docs-meta-index-detaches-folder-index.md b/.changeset/docs-meta-index-detaches-folder-index.md new file mode 100644 index 0000000000..dd39644425 --- /dev/null +++ b/.changeset/docs-meta-index-detaches-folder-index.md @@ -0,0 +1,41 @@ +--- +"@objectstack/docs": patch +--- + +fix(docs): stop listing `"index"` in `meta.json` `pages` — it detaches the folder index and shortens 164 breadcrumb trails (#12352) + +Fumadocs attaches a folder's `index.mdx` as that folder's tree `index` node +**only when the folder's `meta.json` does not list it** in `pages`. Listing it +makes the page an ordinary child instead, and the folder node reaches every tree +consumer with a `name` and no `url` — `loader-*.js`, `buildFolder()`: + +```js +if (indexPath) { + if (excludedPaths.has(indexPath)) delete node.index; // "index" was listed + else excludedPaths.add(indexPath); +} +``` + +Two surfaces read that one node, and both were degraded: + +- **Breadcrumb.** `getBreadcrumbItems()` links a folder crumb to `item.index?.url`, + so an un-linkable ancestor is dropped rather than emitted name-only (Google + requires `item` on every `BreadcrumbList` entry but the last). 172 of 404 doc + pages advertised a two-level site structure they do not have. +- **Sidebar.** `node.index ? SidebarFolderLink : SidebarFolderTrigger` — the + section header was inert text, and the section's own overview page sat below it + as a child, in six cases under a label identical to the header's. + +`"index"` is removed from 16 of the 17 `meta.json` files that listed it. It was +the first `pages` entry in 15 of them and the first entry after the +`---Start Here---` separator in `getting-started`, so no other entry's position +depends on it: the measured tree delta is exactly 16 folder headers going +`TRIGGER` → `LINK` and 16 index children leaving the child list, with every +removed child's URL now the header's `href` and no other line moved. + +Short trails: **172 → 8**. The remaining 8 are `content/docs/releases/`, which +this PR does not touch — that directory is fenced by AGENTS.md, and its +`meta.json` still lists `"index"`. + +No consumer-side change: `app/[lang]/docs/[[...slug]]/page.tsx` reconstructs no +URLs, deliberately, so a producer defect of this shape stays visible. diff --git a/apps/docs/app/[lang]/docs/[[...slug]]/page.tsx b/apps/docs/app/[lang]/docs/[[...slug]]/page.tsx index d4c7524139..a3724055ae 100644 --- a/apps/docs/app/[lang]/docs/[[...slug]]/page.tsx +++ b/apps/docs/app/[lang]/docs/[[...slug]]/page.tsx @@ -39,23 +39,21 @@ type DocPage = NonNullable>; * `index` node. ⛔ Nothing here splits `page.url` on `/`, and nothing constructs a * URL the loader has not already produced. * - * ⚠️ **An ancestor arrives without a URL more often than not, and this drops it.** - * Measured against a local production build, not inferred: fumadocs attaches a - * folder's `index.mdx` as that folder's `index` node only when the folder's - * `meta.json` does **not** list `"index"` in `pages`. 17 of the 35 `meta.json` - * files under `content/docs` do list it, so their folder nodes carry a - * `name` and no `url`, and 172 of 403 doc pages therefore ship a trail that skips - * its section. Confirmed causally by deleting that one line from - * `content/docs/data-modeling/meta.json` and rebuilding: the section crumb - * appeared, linked, while an untouched control section stayed short. + * ⚠️ **An ancestor can arrive without a URL, and this drops it.** Fumadocs + * attaches a folder's `index.mdx` as that folder's `index` node only when the + * folder's `meta.json` does **not** list `"index"` in `pages`; a folder that + * lists it reaches this walk with a `name` and no `url`. That was once 17 of the + * 35 `meta.json` files under `content/docs`, shortening 172 of 404 trails. 16 of + * the 17 were fixed producer-side (#12352) and 8 short trails remain, all under + * `content/docs/releases/` — a directory AGENTS.md fences off, so its `meta.json` + * still lists `"index"`. The condition is therefore live, just rare. * - * ⛔ The missing URL is deliberately **not** reconstructed here. The folder's index - * page exists, is in the sitemap and answers 200 — the defect is in the content - * config that hides it from the tree, not in this consumer, and a lookup that - * re-derived it would make a producer bug invisible and permanent. Google requires - * `item` on every crumb but the last, so a name-only crumb is not an option - * either. Filed separately; when it lands, these trails complete with no change to - * this file. + * ⛔ The missing URL is deliberately **not** reconstructed here — that fence is + * the reason #12352 was fixable at all. The folder's index page exists, is in the + * sitemap and answers 200 — the defect is in the content config that hides it + * from the tree, not in this consumer, and a lookup that re-derived it would make + * a producer bug invisible and permanent. Google requires `item` on every crumb + * but the last, so a name-only crumb is not an option either. * * Two things the tree cannot supply are added around it, both from data this * page already holds: diff --git a/content/docs/ai/meta.json b/content/docs/ai/meta.json index 649174c45c..1f5c5a6070 100644 --- a/content/docs/ai/meta.json +++ b/content/docs/ai/meta.json @@ -1,7 +1,6 @@ { "title": "AI", "pages": [ - "index", "connect-mcp", "agents", "actions-as-tools", diff --git a/content/docs/api/meta.json b/content/docs/api/meta.json index 196b470839..fb386af30c 100644 --- a/content/docs/api/meta.json +++ b/content/docs/api/meta.json @@ -1,7 +1,6 @@ { "title": "API & SDK", "pages": [ - "index", "data-api", "metadata-api", "plugin-endpoints", diff --git a/content/docs/automation/meta.json b/content/docs/automation/meta.json index 6e2388d113..c54511d22e 100644 --- a/content/docs/automation/meta.json +++ b/content/docs/automation/meta.json @@ -1,7 +1,6 @@ { "title": "Automation", "pages": [ - "index", "hooks", "hook-bodies", "flows", diff --git a/content/docs/capabilities/meta.json b/content/docs/capabilities/meta.json index 993aafaa55..91332d5178 100644 --- a/content/docs/capabilities/meta.json +++ b/content/docs/capabilities/meta.json @@ -1,7 +1,6 @@ { "title": "What Can It Do?", "pages": [ - "index", "data", "views", "forms", diff --git a/content/docs/concepts/meta.json b/content/docs/concepts/meta.json index a22d51daac..966bcd92c8 100644 --- a/content/docs/concepts/meta.json +++ b/content/docs/concepts/meta.json @@ -1,7 +1,6 @@ { "title": "Core Concepts", "pages": [ - "index", "architecture", "metadata-driven", "metadata-lifecycle", diff --git a/content/docs/data-modeling/meta.json b/content/docs/data-modeling/meta.json index 25bf32b75c..0a2e03a661 100644 --- a/content/docs/data-modeling/meta.json +++ b/content/docs/data-modeling/meta.json @@ -1,7 +1,6 @@ { "title": "Data Modeling", "pages": [ - "index", "schema-design", "objects", "fields", diff --git a/content/docs/deployment/meta.json b/content/docs/deployment/meta.json index 9dfb59e3ac..2165832ed4 100644 --- a/content/docs/deployment/meta.json +++ b/content/docs/deployment/meta.json @@ -1,7 +1,6 @@ { "title": "Deployment & Operations", "pages": [ - "index", "self-hosting", "production-readiness", "backup-restore", diff --git a/content/docs/getting-started/meta.json b/content/docs/getting-started/meta.json index 872357106d..ed32134231 100644 --- a/content/docs/getting-started/meta.json +++ b/content/docs/getting-started/meta.json @@ -2,7 +2,6 @@ "title": "Get Started", "pages": [ "---Start Here---", - "index", "how-ai-development-works", "build-with-claude-code", "your-first-project", diff --git a/content/docs/kernel/contracts/meta.json b/content/docs/kernel/contracts/meta.json index 205cf53111..29b7259f89 100644 --- a/content/docs/kernel/contracts/meta.json +++ b/content/docs/kernel/contracts/meta.json @@ -1,4 +1,4 @@ { "title": "Service Contracts", - "pages": ["index", "metadata-service", "auth-service", "storage-service", "data-engine", "cache-service"] + "pages": ["metadata-service", "auth-service", "storage-service", "data-engine", "cache-service"] } diff --git a/content/docs/kernel/meta.json b/content/docs/kernel/meta.json index 081e9463d1..f3a5fb2dfa 100644 --- a/content/docs/kernel/meta.json +++ b/content/docs/kernel/meta.json @@ -1,7 +1,6 @@ { "title": "Kernel & Services", "pages": [ - "index", "architecture", "events", "services", diff --git a/content/docs/kernel/runtime-services/meta.json b/content/docs/kernel/runtime-services/meta.json index e6f85138cc..d46a31c9c4 100644 --- a/content/docs/kernel/runtime-services/meta.json +++ b/content/docs/kernel/runtime-services/meta.json @@ -1,7 +1,6 @@ { "title": "Runtime Services", "pages": [ - "index", "data-service", "sharing-service", "audit-service", diff --git a/content/docs/permissions/meta.json b/content/docs/permissions/meta.json index 9a09fc241f..953bc94213 100644 --- a/content/docs/permissions/meta.json +++ b/content/docs/permissions/meta.json @@ -1,7 +1,6 @@ { "title": "Permissions & Identity", "pages": [ - "index", "administrator-guide", "authentication", "sso", diff --git a/content/docs/plugins/meta.json b/content/docs/plugins/meta.json index 7b82331439..797641cce9 100644 --- a/content/docs/plugins/meta.json +++ b/content/docs/plugins/meta.json @@ -1,7 +1,6 @@ { "title": "Plugins & Packages", "pages": [ - "index", "anatomy", "development", "packages", diff --git a/content/docs/protocol/kernel/meta.json b/content/docs/protocol/kernel/meta.json index 57005a45bf..e2b83e22bf 100644 --- a/content/docs/protocol/kernel/meta.json +++ b/content/docs/protocol/kernel/meta.json @@ -1,7 +1,6 @@ { "title": "System Protocol", "pages": [ - "index", "lifecycle", "http-protocol", "realtime-protocol", diff --git a/content/docs/protocol/meta.json b/content/docs/protocol/meta.json index 820a01f096..7cd641f3d7 100644 --- a/content/docs/protocol/meta.json +++ b/content/docs/protocol/meta.json @@ -1,7 +1,6 @@ { "title": "Protocol Spec", "pages": [ - "index", "diagram", "objectql", "objectui", diff --git a/content/docs/ui/meta.json b/content/docs/ui/meta.json index 1464d86d2f..235850bb98 100644 --- a/content/docs/ui/meta.json +++ b/content/docs/ui/meta.json @@ -1,7 +1,6 @@ { "title": "Views & Apps", "pages": [ - "index", "apps", "pages", "react-pages",