@mui/internal-docs-infra 0.12.1-canary.45 → 0.12.1-canary.46

package/createSitemap/index.d.mts

@@ -1 +1,2 @@
-export * from "./createSitemap.mjs";
+export * from "./createSitemap.mjs";
+export type * from "./types.mjs";

package/createSitemap/types.d.mts

@@ -41,11 +41,30 @@ export interface SitemapPage {
   skipDetailSection?: boolean;
   audience?: Audience;
   index?: boolean;
+  /**
+   * The title of the route-group section this page is listed under in a grouped index
+   * (e.g. `Components`), resolved from the page's route group. `null` for a page in a flat
+   * index or with no route group, so the field is always present. Useful for
+   * grouping/faceting search results.
+   */
+  section: string | null;
   image?: {
     url: string;
     alt?: string;
   };
 }
+/**
+ * A route-group section heading in a grouped index (see `SitemapSectionData.sections`).
+ * Maps a Next.js route group to the human-editable heading its pages are listed under.
+ */
+export interface PageIndexSection {
+  /** The route group this section collects (e.g. `(components)`). */
+  group: string;
+  /** The (human-editable) heading text shown for the section. */
+  title: string;
+  /** Heading depth for the section title. Defaults to 2 (`##`). */
+  depth?: number;
+}
 /**
  * Section data from sitemap
  */
@@ -53,6 +72,14 @@ export interface SitemapSectionData {
   title: string;
   prefix: string;
   pages: SitemapPage[];
+  /**
+   * Ordered route-group sections when the index is grouped (its `##` subtitles), so
+   * search can recover the sections a page belongs to. An empty array for a flat index,
+   * so the field is always present.
+   */
+  sections: PageIndexSection[];
+  /** Heading of the detail-region wrapper in a grouped index (defaults to `Details`). */
+  detailsSectionTitle?: string;
 }
 /**
  * Orama schema property types

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mui/internal-docs-infra",
-  "version": "0.12.1-canary.45",
+  "version": "0.12.1-canary.46",
   "author": "MUI Team",
   "description": "MUI Infra - internal documentation creation tools.",
   "license": "MIT",
@@ -281,6 +281,26 @@
         "default": "./createSitemap/types.mjs"
       }
     },
+    "./resolvePageUrl": {
+      "import": {
+        "types": "./resolvePageUrl/index.d.mts",
+        "default": "./resolvePageUrl/index.mjs"
+      },
+      "default": {
+        "types": "./resolvePageUrl/index.d.mts",
+        "default": "./resolvePageUrl/index.mjs"
+      }
+    },
+    "./routeGroups": {
+      "import": {
+        "types": "./pipeline/loaderUtils/stripRouteGroups.d.mts",
+        "default": "./pipeline/loaderUtils/stripRouteGroups.mjs"
+      },
+      "default": {
+        "types": "./pipeline/loaderUtils/stripRouteGroups.d.mts",
+        "default": "./pipeline/loaderUtils/stripRouteGroups.mjs"
+      }
+    },
     "./useStream": {
       "import": {
         "types": "./useStream/index.d.mts",
@@ -795,5 +815,5 @@
   "bin": {
     "docs-infra": "./cli/index.mjs"
   },
-  "gitSha": "1c5627440adc8bc5990c9b1c95fb4b74d375345e"
+  "gitSha": "0534275eee6a8935af28abb295f1ed280d459e95"
 }

package/pipeline/loadPrecomputedSitemap/loadPrecomputedSitemap.d.mts

@@ -8,7 +8,7 @@ export type LoaderOptions = {
   };
   /**
    * Directory for the sha256-validated JSON cache of parsed page indexes. When set,
-   * unchanged indexes are read from `{cacheDir}/pages-index/{route}.json` instead of
+   * unchanged indexes are read from `{cacheDir}/pages-index-v2/{route}.json` instead of
    * being re-parsed.
    */
   cacheDir?: string;

package/pipeline/loadServerPageIndex/enrichPageIndex.mjs

@@ -1,5 +1,5 @@
 import { extractPrefixAndTitle, stripTitleMarkdown } from "./extractPrefixAndTitle.mjs";
-import { collapseInlineWhitespace } from "../syncPageIndex/metadataToMarkdown.mjs";
+import { collapseInlineWhitespace, createPageSectionResolver } from "../syncPageIndex/metadataToMarkdown.mjs";
 /**
  * Converts parsed page-index metadata into the `SitemapSectionData` read-model.
  *
@@ -18,10 +18,15 @@ export function enrichPageIndex(metadata, absolutePath, rootContext) {
     prefix,
     title
   } = extractPrefixAndTitle(absolutePath, rootContext);
+
+  // Resolve each page's section title from its route group (grouped indexes only).
+  const resolveSection = createPageSectionResolver(metadata.sections);
   return {
     ...metadata,
     prefix,
     title,
+    // Always present so consumers never branch on absence: an empty array for a flat index.
+    sections: metadata.sections ?? [],
     // Normalize the index's own (leaked) description like the parser. Spread instead of an explicit
     // key because SitemapSectionData does not declare `description`.
     ...(metadata.description !== undefined ? {
@@ -35,6 +40,7 @@ export function enrichPageIndex(metadata, absolutePath, rootContext) {
       const {
         descriptionMarkdown,
         sections,
+        sectionGroup,
         ...pageWithoutMarkdown
       } = page;
       return {
@@ -43,7 +49,11 @@ export function enrichPageIndex(metadata, absolutePath, rootContext) {
         keywords: page.keywords?.map(collapseInlineWhitespace),
         types: page.types?.map(collapseInlineWhitespace),
         // Strip titleMarkdown from the sections hierarchy.
-        sections: sections ? stripTitleMarkdown(sections) : undefined
+        sections: sections ? stripTitleMarkdown(sections) : undefined,
+        // Resolve the route-group section title for grouped indexes (search faceting),
+        // honoring the header a human filed an otherwise-ungrouped page under. Always present
+        // (`null` when the page has no section) so consumers never branch on absence.
+        section: resolveSection(page.path, sectionGroup) ?? null
       };
     })
   };

package/pipeline/loadServerPageIndex/extractPrefixAndTitle.mjs

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import { isRouteGroup } from "../loaderUtils/stripRouteGroups.mjs";
 /**
  * Converts a path segment to a title
  * e.g., "docs-infra" -> "Docs Infra", "components" -> "Components"
@@ -58,7 +59,7 @@ export function extractPrefixAndTitle(absolutePath, rootContext) {
       return false;
     }
     // Filter out Next.js route groups (e.g., '(public)', '(content)')
-    if (seg.startsWith('(') && seg.endsWith(')')) {
+    if (isRouteGroup(seg)) {
       return false;
     }
     // Filter out current directory markers

package/pipeline/loadServerPageIndex/loadServerPageIndex.d.mts

@@ -11,7 +11,7 @@ export interface CreateLoadServerPageIndexOptions {
   /**
    * Directory for the sha256-validated JSON cache of parsed page indexes.
    *
-   * When set, a read first checks `{cacheDir}/pages-index/{route}.json`; on a hash
+   * When set, a read first checks `{cacheDir}/pages-index-v2/{route}.json`; on a hash
    * match it returns the cached data and skips the markdown parse, and on a miss it
    * parses, writes the cache, and returns. When unset, no cache is read or written.
    */

package/pipeline/loadServerPageIndex/resolvePageIndexCacheKey.d.mts

@@ -1,5 +1,12 @@
-/** Cache namespace (subdirectory) for page-index entries. */
-export declare const PAGE_INDEX_CACHE_NAMESPACE = "pages-index";
+/**
+ * Cache namespace (subdirectory) for page-index entries. The `-v2` suffix is a schema version:
+ * grouped indexes added always-present `sections` and per-page `section` fields to the cached
+ * read-model, so a pre-existing `pages-index` entry (keyed only by content hash) could otherwise
+ * survive a docs-infra upgrade and serve the old shape for an unchanged index file. Bumping the
+ * namespace forces a clean miss the first time the new code runs. Bump again on any future
+ * breaking change to the cached page-index shape.
+ */
+export declare const PAGE_INDEX_CACHE_NAMESPACE = "pages-index-v2";
 /**
  * Derives the cache key for a page-index file from its path, reusing the same
  * route derivation as the loaded data so a writer and reader of the same index

package/pipeline/loadServerPageIndex/resolvePageIndexCacheKey.mjs

@@ -1,7 +1,14 @@
 import { extractPrefixAndTitle } from "./extractPrefixAndTitle.mjs";
 
-/** Cache namespace (subdirectory) for page-index entries. */
-export const PAGE_INDEX_CACHE_NAMESPACE = 'pages-index';
+/**
+ * Cache namespace (subdirectory) for page-index entries. The `-v2` suffix is a schema version:
+ * grouped indexes added always-present `sections` and per-page `section` fields to the cached
+ * read-model, so a pre-existing `pages-index` entry (keyed only by content hash) could otherwise
+ * survive a docs-infra upgrade and serve the old shape for an unchanged index file. Bumping the
+ * namespace forces a clean miss the first time the new code runs. Bump again on any future
+ * breaking change to the cached page-index shape.
+ */
+export const PAGE_INDEX_CACHE_NAMESPACE = 'pages-index-v2';
 
 /**
  * Derives the cache key for a page-index file from its path, reusing the same

package/pipeline/loaderUtils/extractNameAndSlugFromUrl.mjs

@@ -1,4 +1,5 @@
 import { fileUrlToPortablePath } from "./fileUrlToPortablePath.mjs";
+import { kebabToTitleCase } from "./kebabToTitleCase.mjs";
 
 /**
  * Extracts and formats a name and slug from a URL path.
@@ -42,37 +43,6 @@ function camelToTitleCase(camelCase) {
   .replace(/^./, str => str.toUpperCase());
 }
 
-/**
- * Known brand names and acronyms that have a canonical capitalization.
- * Keys are lowercase, values are the canonical form to use in titles.
- */
-const BRAND_NAME_OVERRIDES = {
-  javascript: 'JavaScript',
-  typescript: 'TypeScript'
-};
-
-/**
- * Capitalizes a single word, applying brand-name overrides when applicable.
- */
-function capitalizeWord(word) {
-  const lower = word.toLowerCase();
-  const override = BRAND_NAME_OVERRIDES[lower];
-  if (override) {
-    return override;
-  }
-  return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
-}
-
-/**
- * Converts a kebab-case string to Title Case
- * @param kebabCase - The kebab-case string to convert
- * @returns Title case string
- */
-function kebabToTitleCase(kebabCase) {
-  return kebabCase.split(/[-_]/) // Split on both hyphens and underscores
-  .map(capitalizeWord).join(' ');
-}
-
 /**
  * Detects if a string is camelCase or PascalCase
  * @param str - The string to check

package/pipeline/loaderUtils/index.d.mts

@@ -7,4 +7,5 @@ export * from "./extractNameAndSlugFromUrl.mjs";
 export * from "./externalsToPackages.mjs";
 export * from "./fileUrlToPortablePath.mjs";
 export * from "./getLanguageFromExtension.mjs";
-export * from "./generateFileSlug.mjs";
+export * from "./generateFileSlug.mjs";
+export * from "./stripRouteGroups.mjs";

package/pipeline/loaderUtils/index.mjs

@@ -7,4 +7,5 @@ export * from "./extractNameAndSlugFromUrl.mjs";
 export * from "./externalsToPackages.mjs";
 export * from "./fileUrlToPortablePath.mjs";
 export * from "./getLanguageFromExtension.mjs";
-export * from "./generateFileSlug.mjs";
+export * from "./generateFileSlug.mjs";
+export * from "./stripRouteGroups.mjs";

package/pipeline/loaderUtils/kebabToTitleCase.d.mts

@@ -0,0 +1,11 @@
+/**
+ * Converts a kebab-case (or snake_case) string to Title Case, honoring brand-name overrides
+ * (e.g. `javascript` -> `JavaScript`). This is the single title-casing rule shared by the
+ * producers that turn a slug/folder name into a display title — directory-derived index titles,
+ * URL-segment names, and route-group section headings — so those titles never diverge.
+ *
+ * @example kebabToTitleCase('alert-dialog') -> 'Alert Dialog'
+ * @example kebabToTitleCase('getting_started') -> 'Getting Started'
+ * @example kebabToTitleCase('typescript') -> 'TypeScript'
+ */
+export declare function kebabToTitleCase(kebabCase: string): string;

package/pipeline/loaderUtils/kebabToTitleCase.mjs

@@ -0,0 +1,34 @@
+/**
+ * Known brand names and acronyms that have a canonical capitalization.
+ * Keys are lowercase, values are the canonical form to use in titles.
+ */
+const BRAND_NAME_OVERRIDES = {
+  javascript: 'JavaScript',
+  typescript: 'TypeScript'
+};
+
+/**
+ * Capitalizes a single word, applying brand-name overrides when applicable.
+ */
+function capitalizeWord(word) {
+  const lower = word.toLowerCase();
+  const override = BRAND_NAME_OVERRIDES[lower];
+  if (override) {
+    return override;
+  }
+  return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
+}
+
+/**
+ * Converts a kebab-case (or snake_case) string to Title Case, honoring brand-name overrides
+ * (e.g. `javascript` -> `JavaScript`). This is the single title-casing rule shared by the
+ * producers that turn a slug/folder name into a display title — directory-derived index titles,
+ * URL-segment names, and route-group section headings — so those titles never diverge.
+ *
+ * @example kebabToTitleCase('alert-dialog') -> 'Alert Dialog'
+ * @example kebabToTitleCase('getting_started') -> 'Getting Started'
+ * @example kebabToTitleCase('typescript') -> 'TypeScript'
+ */
+export function kebabToTitleCase(kebabCase) {
+  return kebabCase.split(/[-_]/).map(capitalizeWord).join(' ');
+}

package/pipeline/loaderUtils/stripRouteGroups.d.mts

@@ -0,0 +1,36 @@
+/**
+ * Whether a single path segment is a Next.js route group: a directory name wrapped in
+ * parentheses (e.g. `(overview)`). Route groups organize files without appearing in the public
+ * URL. This is the one shared definition used by page grouping, parent-index resolution, and
+ * path-to-URL resolution.
+ *
+ * Because it tests a whole segment, a segment that merely contains parentheses (e.g.
+ * `(draft)notes`) is not a route group and is kept.
+ *
+ * @example isRouteGroup('(overview)') -> true
+ * @example isRouteGroup('components') -> false
+ * @example isRouteGroup('(draft)notes') -> false
+ */
+export declare function isRouteGroup(segment: string): boolean;
+/**
+ * The name inside a route-group segment (e.g. `(overview)` -> `overview`), or `undefined` when the
+ * segment is not a whole route group. Uses the same whole-segment rule as {@link isRouteGroup}, so
+ * callers get one definition of the parenthesis convention instead of re-deriving it. Useful for
+ * mapping a route group back to a section (e.g. resolving a section's default landing page).
+ *
+ * @example routeGroupName('(overview)') -> 'overview'
+ * @example routeGroupName('components') -> undefined
+ * @example routeGroupName('(draft)notes') -> undefined
+ */
+export declare function routeGroupName(segment: string): string | undefined;
+/**
+ * Removes whole Next.js route-group segments (`(group)`) from a `/`-separated path or URL, since
+ * they do not appear in the public URL, keeping every other segment intact. It splits on `/` and
+ * filters whole segments with {@link isRouteGroup}, so a folder that merely contains parentheses
+ * (e.g. `(draft)notes`) stays in the path. This is the one whole-segment rule the grouped index,
+ * rendered links, and search URL resolution all share.
+ *
+ * @example stripRouteGroupSegments('/components/(inputs)/checkbox') -> '/components/checkbox'
+ * @example stripRouteGroupSegments('/(draft)notes/guide') -> '/(draft)notes/guide'
+ */
+export declare function stripRouteGroupSegments(pathOrUrl: string): string;

package/pipeline/loaderUtils/stripRouteGroups.mjs

@@ -0,0 +1,44 @@
+/**
+ * Whether a single path segment is a Next.js route group: a directory name wrapped in
+ * parentheses (e.g. `(overview)`). Route groups organize files without appearing in the public
+ * URL. This is the one shared definition used by page grouping, parent-index resolution, and
+ * path-to-URL resolution.
+ *
+ * Because it tests a whole segment, a segment that merely contains parentheses (e.g.
+ * `(draft)notes`) is not a route group and is kept.
+ *
+ * @example isRouteGroup('(overview)') -> true
+ * @example isRouteGroup('components') -> false
+ * @example isRouteGroup('(draft)notes') -> false
+ */
+export function isRouteGroup(segment) {
+  return segment.startsWith('(') && segment.endsWith(')');
+}
+
+/**
+ * The name inside a route-group segment (e.g. `(overview)` -> `overview`), or `undefined` when the
+ * segment is not a whole route group. Uses the same whole-segment rule as {@link isRouteGroup}, so
+ * callers get one definition of the parenthesis convention instead of re-deriving it. Useful for
+ * mapping a route group back to a section (e.g. resolving a section's default landing page).
+ *
+ * @example routeGroupName('(overview)') -> 'overview'
+ * @example routeGroupName('components') -> undefined
+ * @example routeGroupName('(draft)notes') -> undefined
+ */
+export function routeGroupName(segment) {
+  return isRouteGroup(segment) ? segment.slice(1, -1) : undefined;
+}
+
+/**
+ * Removes whole Next.js route-group segments (`(group)`) from a `/`-separated path or URL, since
+ * they do not appear in the public URL, keeping every other segment intact. It splits on `/` and
+ * filters whole segments with {@link isRouteGroup}, so a folder that merely contains parentheses
+ * (e.g. `(draft)notes`) stays in the path. This is the one whole-segment rule the grouped index,
+ * rendered links, and search URL resolution all share.
+ *
+ * @example stripRouteGroupSegments('/components/(inputs)/checkbox') -> '/components/checkbox'
+ * @example stripRouteGroupSegments('/(draft)notes/guide') -> '/(draft)notes/guide'
+ */
+export function stripRouteGroupSegments(pathOrUrl) {
+  return pathOrUrl.split('/').filter(segment => !isRouteGroup(segment)).join('/');
+}

package/pipeline/syncPageIndex/mergeMetadataMarkdown.d.mts

@@ -59,6 +59,13 @@ export declare function mergeMetadataPages(existingMarkdown: string | undefined,
  * This allows multiple pages to have the same slug (anchor) while still being treated
  * as distinct pages.
  *
+ * Known limitation: matching is by exact path, so a page whose stored path changes format —
+ * notably an index first regenerated after route groups became path-preserving, where an old
+ * entry `./accordion/page.mdx` no longer matches the new `./(components)/accordion/page.mdx` —
+ * is not reconciled with its old entry and can briefly duplicate. This is accepted rather than
+ * matched by route-group-stripped path (two distinct pages `./(a)/x` and `./(b)/x` share one
+ * stripped path), since grouped indexes are net-new; a stale entry clears once removed by hand.
+ *
  * @param existingMarkdown - The existing markdown content (or undefined if none exists)
  * @param newMetadata - The new metadata to merge in
  * @param options - Optional configuration

package/pipeline/syncPageIndex/mergeMetadataMarkdown.mjs

@@ -1,4 +1,135 @@
-import { markdownToMetadata, metadataToMarkdown } from "./metadataToMarkdown.mjs";
+import { clusterPagesBySection, hasDetailSection, markdownToMetadata, metadataToMarkdown, orderPagesBySection, pageSectionGroup, resolveSectionGroup, routeGroupOfPath, routeGroupToTitle, DEFAULT_DETAILS_SECTION_TITLE } from "./metadataToMarkdown.mjs";
+/**
+ * Derives the ordered route-group sections for an index, given the sections recovered from
+ * the existing file (whose titles/order humans may have edited) and each page's section group
+ * (`pageGroups`, aligned with the merged pages — own route group, else manual placement).
+ * Existing sections are kept in place so renames and reordering survive; a group seen for the
+ * first time is appended with a seeded title. Sections that no longer have any page are
+ * dropped. Returns undefined when no page belongs to a group (flat index).
+ */
+function deriveIndexSections(existingSections, pageGroups) {
+  const usedGroups = new Set(pageGroups.filter(group => group !== undefined));
+  const result = [];
+  const seen = new Set();
+
+  // Keep existing sections (order + human-edited titles), de-duped by group and limited
+  // to groups still in use.
+  for (const section of existingSections ?? []) {
+    if (usedGroups.has(section.group) && !seen.has(section.group)) {
+      seen.add(section.group);
+      result.push(section);
+    }
+  }
+
+  // Append a seeded section for any in-use group not already covered, in page order.
+  for (const group of pageGroups) {
+    if (group && !seen.has(group)) {
+      seen.add(group);
+      result.push({
+        group,
+        title: routeGroupToTitle(group)
+      });
+    }
+  }
+  return result.length > 0 ? result : undefined;
+}
+
+/**
+ * Re-keys each derived section to the group a fresh parse of the rendered file would assign, and
+ * re-points the manual placement (`sectionGroup`) of the ungrouped pages under it to match. Once a
+ * section's last route-grouped page is removed, nothing in the rendered file still encodes the real
+ * `(group)` — the parser can only recover a synthetic id from the heading text (or drop the section
+ * to flat if a local page remains under it). Applying {@link resolveSectionGroup} — the same rule
+ * the parser uses — here keeps the merged (cache) metadata consistent with that parse. Route-grouped
+ * pages derive their section from their own path and are left untouched. Runs on a copy.
+ */
+function reconcileSectionGroups(sections, pages, pageGroups) {
+  const {
+    bySection
+  } = clusterPagesBySection(pages, sections, pageGroups);
+
+  // Map each section's current group to the canonical one a parse would assign (undefined = the
+  // section collapses to flat and is dropped).
+  const canonicalByGroup = new Map();
+  const reconciledSections = [];
+  const seen = new Set();
+  for (const section of sections) {
+    const paths = (bySection.get(section.group) ?? []).map(page => page.path);
+    const canonical = resolveSectionGroup(section.title, paths);
+    canonicalByGroup.set(section.group, canonical);
+    if (canonical && !seen.has(canonical)) {
+      seen.add(canonical);
+      reconciledSections.push({
+        ...section,
+        group: canonical
+      });
+    }
+  }
+
+  // Re-point each ungrouped page's manual placement onto the canonical group, and report each
+  // page's resulting section group so the caller need not recompute it. A route-grouped page owns
+  // its group (derived from its path), so it is left untouched.
+  const reconciledPageGroups = [];
+  const reconciledPages = pages.map((page, index) => {
+    const group = pageGroups[index];
+    if (group === undefined || routeGroupOfPath(page.path) !== undefined) {
+      reconciledPageGroups.push(group);
+      return page;
+    }
+    const canonical = canonicalByGroup.get(group);
+    reconciledPageGroups.push(canonical);
+    if (canonical === undefined) {
+      const {
+        sectionGroup,
+        ...rest
+      } = page;
+      return rest;
+    }
+    return {
+      ...page,
+      sectionGroup: canonical
+    };
+  });
+  return {
+    sections: reconciledSections.length > 0 ? reconciledSections : undefined,
+    pages: reconciledPages,
+    pageGroups: reconciledPageGroups
+  };
+}
+
+/**
+ * Derives the grouped fields of a metadata result — sections, the canonically-ordered pages,
+ * and the "Details" wrapper title — from a base set of sections/pages. Pages are reordered
+ * into the section-clustered order the renderer emits, and `detailsSectionTitle` defaults to
+ * the value the renderer would write, so the pre-populated cache matches a fresh parse of the
+ * rendered file on every path (first sync, parse failure, and normal merge alike).
+ */
+function deriveGroupedFields(baseSections, pages, existingDetailsSectionTitle) {
+  // Compute each page's section group once (own route group, else its manual placement) and
+  // key both the section derivation and the page ordering off it, so a section is kept as
+  // long as any page still belongs to it — even an ungrouped link filed under it by hand.
+  let pageGroups = pages.map(pageSectionGroup);
+  let sections = deriveIndexSections(baseSections, pageGroups);
+  let groupedPages = pages;
+  if (sections) {
+    // Reconcile each section's group with the id a fresh parse of the rendered file would assign,
+    // so a warm cache read never diverges from a cold read of the file it wrote.
+    const reconciled = reconcileSectionGroups(sections, groupedPages, pageGroups);
+    sections = reconciled.sections;
+    groupedPages = reconciled.pages;
+    pageGroups = reconciled.pageGroups;
+  }
+  // Mirror the renderer's `## Details` guard: the wrapper — and hence its title — only exists
+  // when the index is grouped AND at least one page actually renders a detail section. A grouped
+  // index made only of external links (all skipDetailSection) writes no wrapper, so a fresh parse
+  // yields no title; the pre-populated cache must agree, or the consistency check diverges.
+  const rendersDetailsWrapper = Boolean(sections) && hasDetailSection(groupedPages);
+  return {
+    sections,
+    pages: sections ? orderPagesBySection(groupedPages, sections, pageGroups) : groupedPages,
+    detailsSectionTitle: rendersDetailsWrapper ? existingDetailsSectionTitle ?? DEFAULT_DETAILS_SECTION_TITLE : undefined
+  };
+}
 
 /**
  * Options for mergeMetadataMarkdown
@@ -26,22 +157,15 @@ export async function mergeMetadataPages(existingMarkdown, newMetadata, options
     preserveExistingTitleAndSlug
   } = options;
 
-  // If no existing markdown, just use the new metadata.
-  // Use the provided wrapper unless it's null (which means remove).
-  if (!existingMarkdown) {
-    return {
-      metadata: newMetadata,
-      indexWrapperComponent: indexWrapperComponent === null ? undefined : indexWrapperComponent
-    };
-  }
-
-  // Parse the existing markdown to get the current order
-  const existingMetadata = await markdownToMetadata(existingMarkdown);
-
-  // If parsing failed, just use the new metadata
+  // With no existing markdown (or if it fails to parse), just use the new metadata. Use the
+  // provided wrapper unless it's null (which means remove).
+  const existingMetadata = existingMarkdown ? await markdownToMetadata(existingMarkdown) : undefined;
   if (!existingMetadata) {
     return {
-      metadata: newMetadata,
+      metadata: {
+        ...newMetadata,
+        ...deriveGroupedFields(newMetadata.sections, newMetadata.pages, newMetadata.detailsSectionTitle)
+      },
       indexWrapperComponent: indexWrapperComponent === null ? undefined : indexWrapperComponent
     };
   }
@@ -91,6 +215,9 @@ export async function mergeMetadataPages(existingMarkdown, newMetadata, options
         tags: existingPage.tags,
         // Preserve skipDetailSection from existing (user-managed for external links)
         skipDetailSection: existingPage.skipDetailSection,
+        // Preserve the section a human filed this page under (user-managed placement for
+        // pages without a route group of their own, e.g. external links).
+        sectionGroup: existingPage.sectionGroup,
         // Preserve sections from existing if new doesn't have them
         sections: newPage.sections || existingPage.sections,
         // Preserve displayTitle (user-managed title override) only if it still
@@ -121,7 +248,7 @@ export async function mergeMetadataPages(existingMarkdown, newMetadata, options
   const alphabeticalSortMarker = "[//]: # 'This section is autogenerated, but the following list order, title, and [Tag]s can be modified, but nothing within the parentheses. Automatically sorted alphabetically.'";
   // TODO: Remove the old marker check once all index files have been migrated to the new format.
   const oldAlphabeticalSortMarker = "[//]: # 'This file is autogenerated, but the following list can be modified. Automatically sorted alphabetically.'";
-  const requestsAlphabeticalSort = existingMarkdown.includes(alphabeticalSortMarker) || existingMarkdown.includes(oldAlphabeticalSortMarker);
+  const requestsAlphabeticalSort = existingMarkdown?.includes(alphabeticalSortMarker) || existingMarkdown?.includes(oldAlphabeticalSortMarker) || false;
   if (requestsAlphabeticalSort) {
     pages = pages.sort((a, b) => {
       const titleA = a.displayTitle ?? a.title ?? a.slug;
@@ -130,11 +257,15 @@ export async function mergeMetadataPages(existingMarkdown, newMetadata, options
     });
   }
 
-  // Create the final metadata with merged pages
+  // Preserve route-group section headings (order + human-edited titles) from the existing
+  // file, appending sections for any newly-seen group; reorder pages into the section-
+  // clustered order the renderer emits; and keep the "Details" wrapper heading, falling back
+  // to the renderer's default when a flat index first becomes grouped — so the pre-populated
+  // cache stays consistent with a fresh parse.
   const mergedMetadata = {
     title: newMetadata.title,
     // Always use the new title
-    pages,
+    ...deriveGroupedFields(existingMetadata.sections, pages, existingMetadata.detailsSectionTitle),
     // Preserve the existing pageMetadata (e.g., robots config) from the current file
     pageMetadata: existingMetadata.pageMetadata
   };
@@ -156,6 +287,13 @@ export async function mergeMetadataPages(existingMarkdown, newMetadata, options
  * This allows multiple pages to have the same slug (anchor) while still being treated
  * as distinct pages.
  *
+ * Known limitation: matching is by exact path, so a page whose stored path changes format —
+ * notably an index first regenerated after route groups became path-preserving, where an old
+ * entry `./accordion/page.mdx` no longer matches the new `./(components)/accordion/page.mdx` —
+ * is not reconciled with its old entry and can briefly duplicate. This is accepted rather than
+ * matched by route-group-stripped path (two distinct pages `./(a)/x` and `./(b)/x` share one
+ * stripped path), since grouped indexes are net-new; a stale entry clears once removed by hand.
+ *
  * @param existingMarkdown - The existing markdown content (or undefined if none exists)
  * @param newMetadata - The new metadata to merge in
  * @param options - Optional configuration