@mui/internal-docs-infra 0.4.1-canary.9 → 0.5.1-canary.0

package/cli/index.mjs

@@ -7,4 +7,4 @@ function getVersion() {
 }
 yargs().scriptName('docs-infra').usage('$0 <command> [args]').command(runValidate).demandCommand(1, 'You need at least one command before moving on').strict().help()
 // MUI_VERSION is set through the code-infra build command.
-.version("0.4.0" || getVersion()).parse(hideBin(process.argv));
+.version("0.5.0" || getVersion()).parse(hideBin(process.argv));

package/createSitemap/createSitemap.mjs

@@ -9,7 +9,7 @@ function isNextJsContext() {
   typeof process.env.__NEXT_PROCESSED_ENV === 'string' ||
   // Next.js build
   typeof process.env.NEXT_PHASE === 'string') // Next.js build phase
-  ;
+;
 }
 
 /**

package/createSitemap/types.d.mts

@@ -1,3 +1,4 @@
+import type { Metadata } from 'next';
 /**
  * Section data structure from sitemap
  */
@@ -35,6 +36,8 @@ export interface SitemapPage {
   exports?: Record<string, SitemapExport>;
   tags?: string[];
   skipDetailSection?: boolean;
+  audience?: Audience;
+  index?: boolean;
   image?: {
     url: string;
     alt?: string;
@@ -59,4 +62,36 @@ export type OramaSchemaType = 'string' | 'number' | 'boolean' | 'string[]' | 'nu
 export interface Sitemap {
   schema: Record<string, OramaSchemaType>;
   data: Record<string, SitemapSectionData>;
-}
+}
+export type Audience = 'private' | 'introductory' | 'intermediate' | 'advanced' | 'business';
+/**
+ * Page metadata type extending Next.js `Metadata`.
+ *
+ * Adds the `audience` field under `other` using the WHATWG MetaExtensions `audience` meta name.
+ * All standard Next.js metadata fields (title, description, openGraph, etc.) remain available.
+ *
+ * @see https://nextjs.org/docs/app/api-reference/functions/generate-metadata#metadata-fields
+ */
+export type NextMetadata = Metadata & {
+  other?: {
+    /**
+     * Categorize the principal intended audience for the page.
+     * Uses the WHATWG MetaExtensions `audience` meta name.
+     *
+     * When omitted, the page is public and intended for all audiences.
+     *
+     * - `'private'`: Internal page, not intended for public consumption.
+     *   Should be paired with `robots: { index: false }` to exclude from public indexing.
+     * - `'introductory'`: Content aimed at beginners.
+     * - `'intermediate'`: Content aimed at intermediate users.
+     * - `'advanced'`: Content aimed at advanced users.
+     * - `'business'`: Content aimed at prospective customers and decision-makers
+     *   (e.g. marketing pages, pricing, product overviews).
+     *
+     * @see https://wiki.whatwg.org/wiki/MetaExtensions
+     * @see https://brittlebit.org/specifications/html-meta-audience/specification-for-html-meta-element-with-name-value-audience.html
+     */
+    audience?: Audience;
+    [key: string]: unknown;
+  };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mui/internal-docs-infra",
-  "version": "0.4.1-canary.9",
+  "version": "0.5.1-canary.0",
   "author": "MUI Team",
   "description": "MUI Infra - internal documentation creation tools.",
   "keywords": [
@@ -22,12 +22,12 @@
   "homepage": "https://github.com/mui/mui-public/tree/master/packages/docs-infra",
   "dependencies": {
     "@babel/runtime": "^7.28.6",
-    "@babel/standalone": "^7.28.6",
+    "@babel/standalone": "^7.29.1",
     "@orama/orama": "^3.1.18",
     "@orama/plugin-qps": "^3.1.18",
     "@orama/stemmers": "^3.1.18",
     "@orama/stopwords": "^3.1.18",
-    "@wooorm/starry-night": "^3.8.0",
+    "@wooorm/starry-night": "^3.9.0",
     "chalk": "^5.6.2",
     "clipboard-copy": "^4.0.1",
     "fflate": "^0.8.2",
@@ -506,5 +506,5 @@
   "bin": {
     "docs-infra": "./cli/index.mjs"
   },
-  "gitSha": "5a397056f9e93982f8e275c0214fc882d8af3b1c"
+  "gitSha": "df142b55588e09b911db8be848c133b0ebad1cc0"
 }

package/pipeline/syncPageIndex/mergeMetadataMarkdown.d.mts

@@ -38,8 +38,8 @@ export interface MergeMetadataMarkdownOptions extends Omit<MetadataToMarkdownOpt
  * @example
  * ```ts
  * const existingMarkdown = `# Components
- * - [Button](#button) - [Full Docs](./button/page.mdx) - A button
- * - [Checkbox](#checkbox) - [Full Docs](./checkbox/page.mdx) - A checkbox
+ * - Button - ([Outline](#button), [Contents](./button/page.mdx)) - A button
+ * - Checkbox - ([Outline](#checkbox), [Contents](./checkbox/page.mdx)) - A checkbox
  * `;
  *
  * const newMetadata = {

package/pipeline/syncPageIndex/mergeMetadataMarkdown.mjs

@@ -24,8 +24,8 @@ import { markdownToMetadata, metadataToMarkdown } from "./metadataToMarkdown.mjs
  * @example
  * ```ts
  * const existingMarkdown = `# Components
- * - [Button](#button) - [Full Docs](./button/page.mdx) - A button
- * - [Checkbox](#checkbox) - [Full Docs](./checkbox/page.mdx) - A checkbox
+ * - Button - ([Outline](#button), [Contents](./button/page.mdx)) - A button
+ * - Checkbox - ([Outline](#checkbox), [Contents](./checkbox/page.mdx)) - A checkbox
  * `;
  *
  * const newMetadata = {
@@ -108,7 +108,11 @@ export async function mergeMetadataMarkdown(existingMarkdown, newMetadata, optio
         // Preserve skipDetailSection from existing (user-managed for external links)
         skipDetailSection: existingPage.skipDetailSection,
         // Preserve sections from existing if new doesn't have them
-        sections: newPage.sections || existingPage.sections
+        sections: newPage.sections || existingPage.sections,
+        // Preserve displayTitle (user-managed title override) only if it still
+        // differs from the new title. If the override now matches the actual title,
+        // clear it so the titles stay in sync going forward.
+        displayTitle: existingPage.displayTitle && existingPage.displayTitle !== newPage.title ? existingPage.displayTitle : undefined
       };
       pages.push(merged);
       addedPaths.add(newPage.path);
@@ -130,12 +134,14 @@ export async function mergeMetadataMarkdown(existingMarkdown, newMetadata, optio
   }
 
   // If alphabetical sorting is requested, sort pages alphabetically by title
-  const alphabeticalSortMarker = "[//]: # 'This file is autogenerated, but the following list can be modified. Automatically sorted alphabetically.'";
-  const requestsAlphabeticalSort = existingMarkdown.includes(alphabeticalSortMarker);
+  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);
   if (requestsAlphabeticalSort) {
     pages = pages.sort((a, b) => {
-      const titleA = a.title || a.slug;
-      const titleB = b.title || b.slug;
+      const titleA = a.displayTitle ?? a.title ?? a.slug;
+      const titleB = b.displayTitle ?? b.title ?? b.slug;
       return titleA.localeCompare(titleB);
     });
   }
@@ -144,7 +150,9 @@ export async function mergeMetadataMarkdown(existingMarkdown, newMetadata, optio
   const mergedMetadata = {
     title: newMetadata.title,
     // Always use the new title
-    pages
+    pages,
+    // Preserve the existing pageMetadata (e.g., robots config) from the current file
+    pageMetadata: existingMetadata.pageMetadata
   };
 
   // Preserve the alphabetical sorting marker if it was present

package/pipeline/syncPageIndex/metadataToMarkdown.d.mts

@@ -1,14 +1,31 @@
 import type { Root } from 'mdast';
 import type { ExtractedMetadata } from "../transformMarkdownMetadata/types.mjs";
+import { Audience } from "../../createSitemap/types.mjs";
 export interface PageMetadata extends ExtractedMetadata {
   /** The slug/path for this page (e.g., 'button', 'checkbox') */
   slug: string;
   /** The relative path to the page's MDX file */
   path: string;
+  /**
+   * User-customized display title for the page.
+   * When set, this overrides `title` in the navigation list and sitemap.
+   * The `title` field continues to be used for the heading section.
+   *
+   * This value is detected automatically: if a user edits the list item text
+   * so it no longer matches the heading, the edited text is preserved here.
+   */
+  displayTitle?: string;
   /** Tags for this entry (e.g., 'New', 'Hot', 'Beta') */
   tags?: string[];
   /** Skip generating detail section for this entry (for external links) */
   skipDetailSection?: boolean;
+  /**
+   * The intended audience for this page.
+   * When omitted, the page is public and intended for all audiences.
+   */
+  audience?: Audience;
+  /** Whether this page is an index page (has the autogenerated comment marker) */
+  index?: boolean;
   /** Component parts with their API metadata (for multi-part components) */
   parts?: Record<string, {
     props?: string[];

package/pipeline/syncPageIndex/metadataToMarkdown.mjs

@@ -32,6 +32,135 @@ function astNodesToMarkdown(nodes) {
  * Options for metadataToMarkdown and metadataToMarkdownAst functions
  */
 
+/**
+ * Serializes a JS value to a JavaScript-style literal string (unquoted keys, trailing commas).
+ * This produces output like `{ robots: { index: false } }` instead of JSON's `{ "robots": { "index": false } }`.
+ */
+function serializeJsValue(value, indent) {
+  if (value === null || value === undefined) {
+    return String(value);
+  }
+  if (typeof value === 'string') {
+    // Use single quotes for strings, escaping any internal single quotes
+    return `'${String(value).replace(/'/g, "\\'")}'`;
+  }
+  if (typeof value !== 'object') {
+    return String(value);
+  }
+  if (Array.isArray(value)) {
+    if (value.length === 0) {
+      return '[]';
+    }
+    const items = value.map(item => `${'  '.repeat(indent + 1)}${serializeJsValue(item, indent + 1)},`);
+    return `[\n${items.join('\n')}\n${'  '.repeat(indent)}]`;
+  }
+  const entries = Object.entries(value);
+  if (entries.length === 0) {
+    return '{}';
+  }
+  const lines = entries.map(([key, val]) => `${'  '.repeat(indent + 1)}${key}: ${serializeJsValue(val, indent + 1)},`);
+  return `{\n${lines.join('\n')}\n${'  '.repeat(indent)}}`;
+}
+
+/**
+ * Gets the status label for a page based on its audience and index flags.
+ *
+ * Status labels in the editable list:
+ * - \"Private\": audience='private', index=false
+ * - \"Index\": audience='private', index=true
+ * - \"Public Index\": audience!='private', index=true
+ * - \"Introductory\": audience='introductory'
+ * - \"Intermediate\": audience='intermediate'
+ * - \"Advanced\": audience='advanced'
+ * - \"Business\": audience='business'
+ */
+function getStatusLabel(page) {
+  const audience = page.audience;
+  const isIndex = page.index ?? false;
+  if (audience === 'private' && isIndex) {
+    return 'Index';
+  }
+  if (audience === 'private' && !isIndex) {
+    return 'Private';
+  }
+  if (audience && audience !== 'private' && isIndex) {
+    const audienceLabel = audience.charAt(0).toUpperCase() + audience.slice(1);
+    return `${audienceLabel} Index`;
+  }
+  if (audience && audience !== 'private') {
+    return audience.charAt(0).toUpperCase() + audience.slice(1);
+  }
+  if (isIndex) {
+    return 'Public Index';
+  }
+  return undefined;
+}
+
+/**
+ * Parses a status label string back into audience/index flags.
+ */
+function parseStatusLabel(label) {
+  const trimmed = label.trim();
+  switch (trimmed) {
+    case 'Private':
+      return {
+        audience: 'private',
+        index: false
+      };
+    case 'Index':
+      return {
+        audience: 'private',
+        index: true
+      };
+    case 'Public Index':
+      return {
+        index: true
+      };
+    case 'Introductory':
+      return {
+        audience: 'introductory',
+        index: false
+      };
+    case 'Introductory Index':
+      return {
+        audience: 'introductory',
+        index: true
+      };
+    case 'Intermediate':
+      return {
+        audience: 'intermediate',
+        index: false
+      };
+    case 'Intermediate Index':
+      return {
+        audience: 'intermediate',
+        index: true
+      };
+    case 'Advanced':
+      return {
+        audience: 'advanced',
+        index: false
+      };
+    case 'Advanced Index':
+      return {
+        audience: 'advanced',
+        index: true
+      };
+    case 'Business':
+      return {
+        audience: 'business',
+        index: false
+      };
+    case 'Business Index':
+      return {
+        audience: 'business',
+        index: true
+      };
+    default:
+      throw new Error(`Unknown status label "${trimmed}". ` + 'Valid labels are: Private, Index, Public Index, Introductory, Introductory Index, ' + 'Intermediate, Intermediate Index, Advanced, Advanced Index, Business, Business Index.');
+  }
+}
+
 /**
  * Converts a HeadingHierarchy into markdown list format
  */
@@ -339,7 +468,7 @@ export function metadataToMarkdownAst(data, options = {}) {
 
   // Add editable section marker
   // Extract just the comment text from the marker (strip [//]: # 'text' wrapper)
-  const defaultMarkerText = 'This file is autogenerated, but the following list can be modified.';
+  const defaultMarkerText = 'This section is autogenerated, but the following list order, title, and [Tag]s can be modified, but nothing within the parentheses.';
   let markerText = defaultMarkerText;
   if (editableMarker) {
     // Extract text between single quotes: [//]: # 'text'
@@ -359,14 +488,15 @@ export function metadataToMarkdownAst(data, options = {}) {
   // Add page list (editable section) as proper list items
   const listItems = [];
   for (const page of pages) {
-    const pageTitle = page.title || page.slug;
+    // List items use displayTitle when the user has overridden the title
+    const listTitle = page.displayTitle ?? page.title ?? page.slug;
 
     // Check if this is a single-link entry (external link or no detail section)
     const isSingleLink = page.skipDetailSection || false;
     let paragraphChildren;
     if (isSingleLink) {
       // Format: - [Title](./path) [Tag1] [Tag2]
-      paragraphChildren = [link(page.path, pageTitle)];
+      paragraphChildren = [link(page.path, listTitle)];
 
       // Add tags if present (directly after link)
       if (page.tags && page.tags.length > 0) {
@@ -375,8 +505,9 @@ export function metadataToMarkdownAst(data, options = {}) {
         }
       }
     } else {
-      // Format: - [Title](#slug) [Tag1] [Tag2] - [Full Docs](./path/page.mdx)
-      paragraphChildren = [link(`#${page.slug}`, pageTitle)];
+      // Format: - Title [Tag1] [Tag2] - (StatusLabel, [Outline](#slug), [Contents](./path))
+      const statusLabel = getStatusLabel(page);
+      paragraphChildren = [text(listTitle)];
 
       // Add tags if present (directly after component name)
       if (page.tags && page.tags.length > 0) {
@@ -385,9 +516,12 @@ export function metadataToMarkdownAst(data, options = {}) {
         }
       }
 
-      // Add separator and Full Docs link
-      paragraphChildren.push(text(' - '));
-      paragraphChildren.push(link(page.path, 'Full Docs'));
+      // Add separator and parenthetical links (status label first if present)
+      paragraphChildren.push(text(statusLabel ? ` - (${statusLabel}, ` : ' - ('));
+      paragraphChildren.push(link(`#${page.slug}`, 'Outline'));
+      paragraphChildren.push(text(', '));
+      paragraphChildren.push(link(page.path, 'Contents'));
+      paragraphChildren.push(text(')'));
     }
     listItems.push({
       type: 'listItem',
@@ -409,7 +543,7 @@ export function metadataToMarkdownAst(data, options = {}) {
   const normalizedPath = typeof path === 'string' ? path.replace(/\\/g, '/') : undefined;
   const trimmedPath = normalizedPath?.replace(/^(src\/app\/|app\/)/, '').replace(/\/page\.mdx$/, '');
   const quotedPath = trimmedPath && /[()]/.test(trimmedPath) ? `"${trimmedPath}"` : trimmedPath;
-  const doNotEditComment = quotedPath ? `This file is autogenerated, DO NOT EDIT AFTER THIS LINE, run: pnpm docs:validate ${quotedPath}` : 'This file is autogenerated, DO NOT EDIT AFTER THIS LINE';
+  const doNotEditComment = quotedPath ? `This section is autogenerated, DO NOT EDIT AFTER THIS LINE, run: pnpm docs:validate ${quotedPath}` : 'This section is autogenerated, DO NOT EDIT AFTER THIS LINE';
   children.push(comment(doNotEditComment));
 
   // Add detailed page sections (non-editable)
@@ -618,6 +752,9 @@ export function metadataToMarkdownAst(data, options = {}) {
     children.push(paragraph([link(page.path, 'Read more')]));
   }
 
+  // Add metadata marker (inside wrapper component if provided)
+  children.push(comment('The above section is autogenerated, but the remainder of the file can be modified.'));
+
   // Close wrapper component if provided
   if (indexWrapperComponent) {
     children.push({
@@ -625,20 +762,16 @@ export function metadataToMarkdownAst(data, options = {}) {
       value: `</${indexWrapperComponent}>`
     });
   }
-
-  // Add metadata export at the end
-  children.push(comment('This file is autogenerated, but the following metadata can be modified.'));
-  let metadataCode;
-  if (pageMetadata && Object.keys(pageMetadata).length > 0) {
-    metadataCode = `export const metadata = ${JSON.stringify(pageMetadata, null, 2)};`;
-  } else {
-    // Default metadata with robots noindex
-    metadataCode = `export const metadata = {
-  robots: {
-    index: false,
-  },
-};`;
-  }
+  const metadataObj = pageMetadata && Object.keys(pageMetadata).length > 0 ? pageMetadata : {
+    robots: {
+      index: false
+    },
+    other: {
+      audience: 'private'
+    }
+  };
+  const typeAnnotation = "/** @type {import('@mui/internal-docs-infra/createSitemap/types').NextMetadata} */";
+  const metadataCode = `export const metadata =\n  ${typeAnnotation} (${serializeJsValue(metadataObj, 1)});`;
   // Output as raw MDX/JSX code (mdxjsEsm node type)
   children.push({
     type: 'mdxjsEsm',
@@ -682,7 +815,7 @@ export function metadataToMarkdown(data, options = {}) {
   }
 
   // Add editable section marker
-  const marker = editableMarker ?? "[//]: # 'This file is autogenerated, but the following list can be modified.'";
+  const marker = editableMarker ?? "[//]: # 'This section is autogenerated, but the following list order, title, and [Tag]s can be modified, but nothing within the parentheses.'";
   lines.push(marker);
   lines.push('');
 
@@ -694,14 +827,15 @@ export function metadataToMarkdown(data, options = {}) {
 
   // Add page list (editable section)
   for (const page of pages) {
-    const pageTitle = page.title || page.slug;
+    // List items use displayTitle when the user has overridden the title
+    const listTitle = page.displayTitle ?? page.title ?? page.slug;
 
     // Check if this is a single-link entry (external link or no detail section)
     const isSingleLink = page.skipDetailSection || false;
     let line;
     if (isSingleLink) {
       // Format: - [Title](./path) [Tag1] [Tag2]
-      line = `- [${pageTitle}](${page.path})`;
+      line = `- [${listTitle}](${page.path})`;
 
       // Add tags if present (directly after link)
       if (page.tags && page.tags.length > 0) {
@@ -710,8 +844,9 @@ export function metadataToMarkdown(data, options = {}) {
         }
       }
     } else {
-      // Format: - [Title](#slug) [Tag1] [Tag2] - [Full Docs](./path/page.mdx)
-      line = `- [${pageTitle}](#${page.slug})`;
+      // Format: - Title [Tag1] [Tag2] - (StatusLabel, [Outline](#slug), [Contents](./path))
+      const statusLabel = getStatusLabel(page);
+      line = `- ${listTitle}`;
 
       // Add tags if present (directly after component name)
       if (page.tags && page.tags.length > 0) {
@@ -720,8 +855,8 @@ export function metadataToMarkdown(data, options = {}) {
         }
       }
 
-      // Add separator and Full Docs link
-      line += ` - [Full Docs](${page.path})`;
+      // Add separator and parenthetical links (status label first if present)
+      line += statusLabel ? ` - (${statusLabel}, [Outline](#${page.slug}), [Contents](${page.path}))` : ` - ([Outline](#${page.slug}), [Contents](${page.path}))`;
     }
     lines.push(line);
   }
@@ -732,7 +867,7 @@ export function metadataToMarkdown(data, options = {}) {
   const normalizedPath = typeof path === 'string' ? path.replace(/\\/g, '/') : undefined;
   const trimmedPath = normalizedPath?.replace(/^(src\/app\/|app\/)/, '').replace(/\/page\.mdx$/, '');
   const quotedPath = trimmedPath && /[()]/.test(trimmedPath) ? `"${trimmedPath}"` : trimmedPath;
-  const doNotEditMarker = quotedPath ? `[//]: # 'This file is autogenerated, DO NOT EDIT AFTER THIS LINE, run: pnpm docs:validate ${quotedPath}'` : "[//]: # 'This file is autogenerated, DO NOT EDIT AFTER THIS LINE'";
+  const doNotEditMarker = quotedPath ? `[//]: # 'This section is autogenerated, DO NOT EDIT AFTER THIS LINE, run: pnpm docs:validate ${quotedPath}'` : "[//]: # 'This section is autogenerated, DO NOT EDIT AFTER THIS LINE'";
   lines.push(doNotEditMarker);
   lines.push('');
 
@@ -856,24 +991,27 @@ export function metadataToMarkdown(data, options = {}) {
     lines.push('');
   }
 
+  // Add metadata marker (inside wrapper component if provided)
+  lines.push("[//]: # 'The above section is autogenerated, but the remainder of the file can be modified.'");
+  lines.push('');
+
   // Close wrapper component if provided
   if (indexWrapperComponent) {
     lines.push(`</${indexWrapperComponent}>`);
     lines.push('');
   }
-
-  // Add metadata export at the end
-  lines.push("[//]: # 'This file is autogenerated, but the following metadata can be modified.'");
-  lines.push('');
+  const TYPE_ANNOTATION = "/** @type {import('@mui/internal-docs-infra/createSitemap/types').NextMetadata} */";
   if (pageMetadata && Object.keys(pageMetadata).length > 0) {
-    lines.push(`export const metadata = ${JSON.stringify(pageMetadata, null, 2)};`);
+    lines.push(`export const metadata =\n  ${TYPE_ANNOTATION} (${serializeJsValue(pageMetadata, 1)});`);
   } else {
-    // Default metadata with robots noindex
-    lines.push(`export const metadata = {
-  robots: {
-    index: false,
-  },
-};`);
+    lines.push(`export const metadata =\n  ${TYPE_ANNOTATION} (${serializeJsValue({
+      robots: {
+        index: false
+      },
+      other: {
+        audience: 'private'
+      }
+    }, 1)});`);
   }
   lines.push('');
 
@@ -891,6 +1029,9 @@ export async function markdownToMetadata(markdown) {
   let pageMetadata;
   let indexWrapperComponent;
   const pages = [];
+  // Track the title from the editable list for each page (by slug)
+  // Used to detect user overrides after the detail section is parsed
+  const listTitles = new Map();
   let currentSection = 'header';
   let currentPage = null;
 
@@ -899,7 +1040,7 @@ export async function markdownToMetadata(markdown) {
     // Track sections based on definition nodes (HTML-style comments)
     if (node.type === 'definition') {
       const defNode = node;
-      if (defNode.title?.includes('following list can be modified')) {
+      if (defNode.title?.includes('following list can be modified') || defNode.title?.includes('following list order')) {
         currentSection = 'editable';
         return;
       }
@@ -907,7 +1048,9 @@ export async function markdownToMetadata(markdown) {
         currentSection = 'details';
         return;
       }
-      if (defNode.title?.includes('following metadata can be modified')) {
+      if (defNode.title?.includes('remainder of the file can be modified') ||
+      // TODO: Remove this old marker check once all index files have been migrated to the new format.
+      defNode.title?.includes('following metadata can be modified')) {
         currentSection = 'metadata';
         return;
       }
@@ -1003,49 +1146,98 @@ export async function markdownToMetadata(markdown) {
             tags: tags.length > 0 ? tags : undefined,
             skipDetailSection: true // Mark as external/single-link entry
           });
+          listTitles.set(slug, pageTitle);
         } else if (links.length >= 2) {
-          // Two-link format: - [Title](#slug) [Tag1] [Tag2] - [Full Docs](./path/page.mdx)
-          const sectionLink = links[0];
-          const docsLink = links[1];
-          const pageTitle = extractPlainTextFromNode(sectionLink);
-          const slug = sectionLink.url.replace('#', ''); // Extract slug from #slug
-          const path = docsLink.url; // Get path from full docs link
-
-          // Extract tags from text nodes between the section link and full docs link
-          // Tags are in the format [Tag] where Tag can be New, Hot, Beta, etc.
-          const tags = [];
-          let foundSectionLink = false;
-          let foundDocsLink = false;
-          for (const child of paragraphNode.children) {
-            if (child === sectionLink) {
-              foundSectionLink = true;
-              continue;
+          const firstChild = paragraphNode.children[0];
+          if (firstChild && firstChild.type === 'text' && firstChild.value.includes(' - (')) {
+            // Format: Title [Tags] - (Status, [Outline](#slug), [Contents](./path))
+            const firstText = firstChild.value;
+            const dashParenIndex = firstText.lastIndexOf(' - (');
+            const titlePart = firstText.substring(0, dashParenIndex);
+
+            // Extract tags from title part
+            const tags = [];
+            const tagRegex = /\[([^\]]+)\]/g;
+            let match = tagRegex.exec(titlePart);
+            while (match !== null) {
+              tags.push(match[1]);
+              match = tagRegex.exec(titlePart);
             }
-            if (child === docsLink) {
-              foundDocsLink = true;
-              break;
+            const cleanTitle = titlePart.replace(/\s*\[[^\]]+\]/g, '').trim();
+
+            // Find Outline and Contents links
+            const outlineLink = links.find(l => extractPlainTextFromNode(l) === 'Outline' || l.url.startsWith('#'));
+            const contentsLink = links.find(l => extractPlainTextFromNode(l) === 'Contents' || !l.url.startsWith('#'));
+            if (outlineLink && contentsLink) {
+              const slug = outlineLink.url.replace('#', '');
+              const pagePath = contentsLink.url;
+
+              // Parse status label from the text before the first link
+              // Format: " - (Status, " or " - ("
+              let parsedAudience;
+              let isIndex = false;
+              const afterDashParen = firstText.substring(dashParenIndex + 4); // after ' - ('
+              if (afterDashParen.length > 0) {
+                // Status label is the text before the first comma that precedes a link
+                const commaIndex = afterDashParen.indexOf(',');
+                if (commaIndex >= 0) {
+                  const statusStr = afterDashParen.substring(0, commaIndex).trim();
+                  if (statusStr.length > 0) {
+                    const status = parseStatusLabel(statusStr);
+                    parsedAudience = status.audience;
+                    isIndex = status.index;
+                  }
+                }
+              }
+              pages.push({
+                slug,
+                path: pagePath,
+                title: cleanTitle,
+                description: 'No description available',
+                tags: tags.length > 0 ? tags : undefined,
+                audience: parsedAudience,
+                index: isIndex || undefined
+              });
+              listTitles.set(slug, cleanTitle);
             }
-            if (foundSectionLink && !foundDocsLink && child.type === 'text') {
-              // Match [Tag] patterns in the text
-              const tagRegex = /\[(\w+)\]/g;
-              let match = tagRegex.exec(child.value);
-              while (match !== null) {
-                tags.push(match[1]);
-                match = tagRegex.exec(child.value);
+          } else {
+            // TODO: Remove this old format parsing once all index files have been migrated.
+            // Old format: - [Title](#slug) [Tag1] [Tag2] - [Full Docs](./path/page.mdx)
+            const sectionLink = links[0];
+            const docsLink = links[1];
+            const pageTitle = extractPlainTextFromNode(sectionLink);
+            const slug = sectionLink.url.replace('#', '');
+            const pagePath = docsLink.url;
+            const tags = [];
+            let foundSectionLink = false;
+            let foundDocsLink = false;
+            for (const child of paragraphNode.children) {
+              if (child === sectionLink) {
+                foundSectionLink = true;
+                continue;
+              }
+              if (child === docsLink) {
+                foundDocsLink = true;
+                break;
+              }
+              if (foundSectionLink && !foundDocsLink && child.type === 'text') {
+                const tagRegex = /\[(\w+)\]/g;
+                let match = tagRegex.exec(child.value);
+                while (match !== null) {
+                  tags.push(match[1]);
+                  match = tagRegex.exec(child.value);
+                }
               }
             }
+            pages.push({
+              slug,
+              path: pagePath,
+              title: pageTitle,
+              description: 'No description available',
+              tags: tags.length > 0 ? tags : undefined
+            });
+            listTitles.set(slug, pageTitle);
           }
-
-          // Only extract slug, path, title, and tags from the editable list
-          // The description will be filled in from the details section
-          pages.push({
-            slug,
-            path,
-            title: pageTitle,
-            description: 'No description available',
-            // Will be updated from details section
-            tags: tags.length > 0 ? tags : undefined
-          });
         }
       }
       return;
@@ -1069,8 +1261,14 @@ export async function markdownToMetadata(markdown) {
             }
           }
           const pageTitle = extractPlainTextFromNode(headingNode);
-          // Find the page in the existing pages array by matching the title
-          const existingPage = pages.find(p => p.title === pageTitle);
+          // Find the page in the existing pages array by matching the title first,
+          // then fall back to slug matching. Slug matching is needed when the user
+          // has renamed the list item (so list title ≠ heading title).
+          let existingPage = pages.find(p => p.title === pageTitle);
+          if (!existingPage) {
+            const derivedSlug = titleToSlug(pageTitle);
+            existingPage = pages.find(p => p.slug === derivedSlug);
+          }
           if (existingPage) {
             // Start updating this existing page
             currentPage = {
@@ -1129,8 +1327,21 @@ export async function markdownToMetadata(markdown) {
           }
         }
 
-        // Skip read more links
+        // Extract path from Read more link for robust page matching.
+        // If the current page's slug doesn't match any page in the list
+        // (e.g., because titleToSlug(heading) ≠ actual slug), the path match
+        // provides a final correction.
         if (paragraphText.startsWith('[Read more]')) {
+          if (currentPage) {
+            const linkNode = paragraphNode.children.find(child => child.type === 'link');
+            if (linkNode) {
+              const readMorePath = linkNode.url;
+              const matchedPage = pages.find(p => p.path === readMorePath);
+              if (matchedPage && currentPage.slug !== matchedPage.slug) {
+                currentPage.slug = matchedPage.slug;
+              }
+            }
+          }
           return;
         }
 
@@ -1160,8 +1371,8 @@ export async function markdownToMetadata(markdown) {
     if (currentSection === 'metadata' && node.type === 'code') {
       const codeNode = node;
       const codeValue = codeNode.value;
-      // Parse the export const metadata = { ... } statement
-      const metadataMatch = codeValue.match(/export\s+const\s+metadata\s*=\s*(\{[\s\S]*\})/);
+      // Parse the export const metadata = /** @type ... */ ({ ... }) or { ... } statement
+      const metadataMatch = codeValue.match(/export\s+const\s+metadata\s*=\s*(?:\/\*\*[^*]*\*\/\s*\()?\s*(\{[\s\S]*\})\)?/);
       if (metadataMatch) {
         try {
           // Use Function constructor to safely parse the object literal
@@ -1177,7 +1388,13 @@ export async function markdownToMetadata(markdown) {
 
   // Also try to parse metadata from raw export statement in the markdown
   // This handles MDX files where the export is not in a code block
-  const metadataExportMatch = markdown.match(/\[\/\/\]: # 'This file is autogenerated, but the following metadata can be modified\.'\s*\n\s*\n\s*export\s+const\s+metadata\s*=\s*(\{[\s\S]*?\n\})/);
+  // The regex allows optional HTML closing tags (e.g., </PagesIndex>) between the marker and the export
+  // Greedy `[\s\S]*` ensures the capture extends to the LAST `\n\s*\}` (outermost closing brace)
+  // rather than stopping at an inner closing brace. This is safe because the metadata
+  // export is always the last statement in the file.
+  const metadataExportMatch = markdown.match(/\[\/\/\]: # 'The above section is autogenerated, but the remainder of the file can be modified\.'[\s\S]*?export\s+const\s+metadata\s*=\s*(?:\/\*\*[^*]*\*\/\s*\()?\s*(\{[\s\S]*\n\s*\})\)?\s*;?/) ??
+  // TODO: Remove this old marker match once all index files have been migrated to the new format.
+  markdown.match(/\[\/\/\]: # 'This (?:section|file) is autogenerated, but the following metadata can be modified\.'[\s\S]*?export\s+const\s+metadata\s*=\s*(?:\/\*\*[^*]*\*\/\s*\()?\s*(\{[\s\S]*\n\s*\})\)?\s*;?/);
   if (metadataExportMatch && !pageMetadata) {
     try {
       // eslint-disable-next-line no-new-func
@@ -1200,6 +1417,16 @@ export async function markdownToMetadata(markdown) {
       }
     }
   }
+
+  // Detect title overrides: compare the list title with the heading title.
+  // After the detail section is parsed, page.title reflects the heading's title.
+  // If the list had a different title, the user renamed it — store as displayTitle.
+  for (const page of pages) {
+    const listTitle = listTitles.get(page.slug);
+    if (listTitle && listTitle !== page.title) {
+      page.displayTitle = listTitle;
+    }
+  }
   if (!title) {
     return null;
   }

package/pipeline/syncPageIndex/syncPageIndex.mjs

@@ -173,7 +173,9 @@ export async function syncPageIndex(options) {
 
   // Step 1.5: Verify the file has the autogeneration marker if it exists
   if (fileExists && existingContent) {
-    const hasMarker = existingContent.includes("[//]: # 'This file is autogenerated");
+    const hasMarker = existingContent.includes("[//]: # 'This section is autogenerated") ||
+    // TODO: Remove this old marker check once all index files have been migrated to the new format.
+    existingContent.includes("[//]: # 'This file is autogenerated");
     if (!hasMarker) {
       // File exists but doesn't have the autogeneration marker - skip updating it
       return;
@@ -226,6 +228,7 @@ export async function syncPageIndex(options) {
   }
   let release;
   let mergedPages = []; // Store merged pages for parent update
+  let currentPageMetadata; // Store the index's own metadata for parent update
 
   try {
     // Step 5: Acquire lock on the index file
@@ -258,6 +261,7 @@ export async function syncPageIndex(options) {
       const parsed = await markdownToMetadata(currentMarkdown);
       if (parsed) {
         currentPages = parsed.pages;
+        currentPageMetadata = parsed.pageMetadata;
       }
     }
 
@@ -349,6 +353,16 @@ export async function syncPageIndex(options) {
         description: 'No description available'
       };
 
+      // Determine audience/index flags from the index page's own metadata
+      const audience = currentPageMetadata?.other?.audience;
+      if (audience) {
+        indexMetadata.audience = audience;
+      }
+      // An index page with child pages is always an index
+      if (mergedPages.length > 0) {
+        indexMetadata.index = true;
+      }
+
       // Convert child pages to sections format (no subsections, just page names)
       // Use mergedPages which contains the complete merged state
       // Skip single-link entries (external links) as they don't have detail sections
@@ -360,13 +374,10 @@ export async function syncPageIndex(options) {
             continue;
           }
           sections[childPage.slug] = {
-            title: childPage.title || childPage.slug,
-            titleMarkdown: childPage.title ? [{
-              type: 'text',
-              value: childPage.title
-            }] : [{
+            title: childPage.displayTitle ?? childPage.title ?? childPage.slug,
+            titleMarkdown: [{
               type: 'text',
-              value: childPage.slug
+              value: childPage.displayTitle ?? childPage.title ?? childPage.slug
             }],
             children: {} // Don't include any subsections in parent index
           };

package/pipeline/transformMarkdownMetadata/transformMarkdownMetadata.mjs

@@ -230,7 +230,8 @@ function toPageMetadata(metadata, filePath, options = {}) {
     keywords: metadata.keywords,
     sections: metadata.sections,
     embeddings: metadata.embeddings,
-    image: metadata.image
+    image: metadata.image,
+    audience: metadata.other?.audience
   };
 }
 
@@ -637,7 +638,9 @@ export const transformMarkdownMetadata = (options = {}) => {
       }
 
       // Check if this is an autogenerated index file
-      if (fileContent && fileContent.includes("[//]: # 'This file is autogenerated")) {
+      if (fileContent && (fileContent.includes("[//]: # 'This section is autogenerated") ||
+      // TODO: Remove this old marker check once all index files have been migrated to the new format.
+      fileContent.includes("[//]: # 'This file is autogenerated"))) {
         // Parse the page list metadata from the markdown
         const pagesMetadata = await markdownToMetadata(fileContent);
         if (pagesMetadata) {
@@ -687,7 +690,7 @@ export const transformMarkdownMetadata = (options = {}) => {
             title: pagesMetadata.title,
             prefix,
             pages: pagesMetadata.pages.map(page => ({
-              title: page.title,
+              title: page.displayTitle ?? page.title,
               slug: page.slug,
               path: page.path,
               description: page.description,
@@ -697,6 +700,8 @@ export const transformMarkdownMetadata = (options = {}) => {
               exports: page.exports,
               tags: page.tags,
               skipDetailSection: page.skipDetailSection,
+              audience: page.audience,
+              index: page.index,
               image: page.image
             }))
           };

package/pipeline/transformMarkdownMetadata/types.d.mts

@@ -1,4 +1,5 @@
 import type { PhrasingContent } from 'mdast';
+import { Audience } from "../../createSitemap/types.mjs";
 /**
  * Plugin options for transformMarkdownMetadata
  */
@@ -101,4 +102,11 @@ export interface ExtractedMetadata {
     url: string;
     alt?: string;
   };
+  robots?: {
+    index?: boolean;
+  };
+  other?: {
+    audience?: Audience;
+    [key: string]: unknown;
+  };
 }

package/useSearch/types.d.mts

@@ -89,6 +89,19 @@ export interface UseSearchOptions {
   boost?: Partial<Record<string, number>>;
   /** Include page categories in groups: "Overview Pages" vs "Pages" */
   includeCategoryInGroup?: boolean;
+  /**
+   * When true, pages with `audience: 'private'` are included in the search index
+   * and default results. Use this for internal deployments where private pages
+   * should be discoverable.
+   *
+   * Typically driven by an environment variable:
+   * ```ts
+   * showPrivatePages: process.env.SHOW_PRIVATE_PAGES === 'true'
+   * ```
+   *
+   * @default false
+   */
+  showPrivatePages?: boolean;
   /**
    * When true, excludes `sections` and `subsections` fields from page-type results.
    * The individual section and subsection entries are still created.

package/useSearch/useSearch.mjs

@@ -308,7 +308,8 @@ export function useSearch(options) {
     enableStemming = true,
     generateSlug,
     flattenPage = defaultFlattenPage,
-    formatResult = defaultFormatResult
+    formatResult = defaultFormatResult,
+    showPrivatePages = false
   } = options;
   const [index, setIndex] = React.useState(null);
   const [defaultResults, setDefaultResults] = React.useState({
@@ -356,6 +357,10 @@ export function useSearch(options) {
       let pageResultsCount = 0;
       Object.entries(sitemap.data).forEach(([_sectionKey, sectionData]) => {
         (sectionData.pages || []).forEach(page => {
+          // Skip private pages in public deployments
+          if (!showPrivatePages && page.audience === 'private') {
+            return;
+          }
           const flattened = flattenPage(page, sectionData, options.includeCategoryInGroup || false, options.excludeSections, generateSlug);
           pages.push(...flattened);
 
@@ -414,7 +419,7 @@ export function useSearch(options) {
       setDefaultResults(defaultResultsValue);
       setResults(defaultResultsValue);
     })();
-  }, [sitemapImport, maxDefaultResults, flattenPage, generateSlug, enableStemming, options.includeCategoryInGroup, options.excludeSections]);
+  }, [sitemapImport, maxDefaultResults, flattenPage, generateSlug, enableStemming, options.includeCategoryInGroup, options.excludeSections, showPrivatePages]);
   const search = React.useCallback(async (value, {
     facets,
     groupBy,

package/withDocsInfra/withDeploymentConfig.mjs

@@ -34,6 +34,8 @@ if ((process.env.CONTEXT === 'production' || process.env.CONTEXT === 'branch-dep
  */
 
 process.env.DEPLOY_ENV = DEPLOY_ENV;
+const SHOW_PRIVATE_PAGES = String(process.env.DEPLOY_ENV !== 'production' && process.env.DEPLOY_ENV !== 'staging');
+process.env.SHOW_PRIVATE_PAGES = SHOW_PRIVATE_PAGES;
 export function withDeploymentConfig(nextConfig) {
   return {
     trailingSlash: true,
@@ -43,6 +45,7 @@ export function withDeploymentConfig(nextConfig) {
     env: {
       // production | staging | pull-request | development
       DEPLOY_ENV,
+      SHOW_PRIVATE_PAGES,
       ...nextConfig.env,
       // https://docs.netlify.com/configure-builds/environment-variables/#git-metadata
       // reference ID (also known as "SHA" or "hash") of the commit we're building.