diff --git a/docs/app/docs-infra/commands/page.mdx b/docs/app/docs-infra/commands/page.mdx index 2cb755fdb..6a543a3a5 100644 --- a/docs/app/docs-infra/commands/page.mdx +++ b/docs/app/docs-infra/commands/page.mdx @@ -12,7 +12,7 @@ The `validate` command ensures that committed files match the expected output. It processes all `page.mdx` files to verify parent indexes are up-to-date, and all `types.ts` files to ensure generated `types.md` documentation is current. -
+
Outline diff --git a/docs/app/docs-infra/components/page.mdx b/docs/app/docs-infra/components/page.mdx index 078df971a..8ac7537c7 100644 --- a/docs/app/docs-infra/components/page.mdx +++ b/docs/app/docs-infra/components/page.mdx @@ -16,7 +16,7 @@ The `CodeHighlighter` component provides a powerful and flexible way to display interactive code examples with syntax highlighting, multiple variants, and live previews. It supports both static code blocks and interactive demos with component previews. -
+
Outline @@ -71,7 +71,7 @@ It supports both static code blocks and interactive demos with component preview The `CodeProvider` component provides client-side functions for fetching source code and highlighting it. It's designed for cases where you need to render code blocks or demos based on client-side state or dynamic content loading. It also provides heavy processing functions that are moved from individual components to the context for better performance and code splitting. -
+
Outline @@ -99,7 +99,7 @@ The `CodeProvider` component provides client-side functions for fetching source The `CodeControllerContext` provides a React context for managing controlled code state in interactive code editing and demo scenarios. It enables real-time code editing with syntax highlighting and live component previews. -
+
Outline @@ -134,7 +134,7 @@ The `CodeControllerContext` provides a React context for managing controlled cod The `CodeExternalsContext` is a simple React context that provides access to external dependencies (modules and components) for demo components. It's primarily used internally by demo client providers created with [`abstractCreateDemoClient`](../../factories/abstract-create-demo-client/page.mdx) to make precomputed externals available to child components. -
+
Outline diff --git a/docs/app/docs-infra/conventions/page.mdx b/docs/app/docs-infra/conventions/page.mdx index 04f91954c..7eb163b1b 100644 --- a/docs/app/docs-infra/conventions/page.mdx +++ b/docs/app/docs-infra/conventions/page.mdx @@ -16,7 +16,7 @@ Every documentation file should be useful as a static markdown document before any React components or interactivity are added. -
+
Outline @@ -39,7 +39,7 @@ All useful content should be represented in the HTML without JavaScript. This ensures crawlers, screen readers, and users on slow connections can access documentation content immediately. -
+
Outline @@ -58,7 +58,7 @@ can access documentation content immediately. A consistent file structure makes it easy to find what you need. The patterns below apply across the repository. -
+
Outline @@ -89,7 +89,7 @@ The patterns below apply across the repository. We use `:` to express hierarchy inside URL fragments. Example: `https://example.com/page#section:subsection` uses `:` to separate a primary section (`section`) from a nested part (`subsection`). The full value appears in an element’s `id`, e.g. `section:subsection`. -
+
Outline diff --git a/docs/app/docs-infra/factories/page.mdx b/docs/app/docs-infra/factories/page.mdx index 84e28d4ff..942e9bbe1 100644 --- a/docs/app/docs-infra/factories/page.mdx +++ b/docs/app/docs-infra/factories/page.mdx @@ -16,7 +16,7 @@ The `abstractCreateDemo` function helps you create structured demo factories that work seamlessly with the [`CodeHighlighter`](../../components/code-highlighter/page.mdx) component ecosystem. It provides a standardized way to create demos that combine component previews with code display, making it easier to build consistent documentation interfaces. -
+
Outline @@ -44,7 +44,7 @@ The `abstractCreateDemo` function helps you create structured demo factories tha The `createSitemap` factory function defines sitemap data for documentation sites. It works with the webpack loader for build-time precomputation in Next.js builds. -
+
Outline @@ -72,7 +72,7 @@ The `createSitemap` factory function defines sitemap data for documentation site The `abstractCreateTypes` function helps you create structured type documentation factories that work seamlessly with the [`loadPrecomputedTypes`](../../pipeline/load-precomputed-types/page.mdx) loader. It provides a standardized way to create type documentation components that display TypeScript type information extracted at build time. -
+
Outline @@ -119,7 +119,7 @@ The `abstractCreateTypes` function helps you create structured type documentatio The `abstractCreateDemoClient` function helps you create client-side demo providers that manage external dependencies for live component demos. It creates provider components that supply externals context to child components, enabling dynamic code execution in the browser. -
+
Outline @@ -150,7 +150,7 @@ The `abstractCreateDemoClient` function helps you create client-side demo provid The `createDemoData` utility creates structured demo metadata and component data for use with the [`CodeHighlighter`](../../components/code-highlighter/page.mdx) system. It processes demo URLs, components, and metadata to create data objects that can be consumed by demo factories and code highlighting systems. -
+
Outline diff --git a/docs/app/docs-infra/hooks/page.mdx b/docs/app/docs-infra/hooks/page.mdx index be7cb1a4e..94ab52041 100644 --- a/docs/app/docs-infra/hooks/page.mdx +++ b/docs/app/docs-infra/hooks/page.mdx @@ -21,7 +21,7 @@ The `useCode` hook provides programmatic access to code display, editing, and transformation functionality within `CodeHighlighter` components. It's designed for scenarios where you need fine-grained control over code behavior or want to build custom code interfaces that focus purely on code management, without component rendering. -
+
Outline @@ -92,7 +92,7 @@ The `useCode` hook provides programmatic access to code display, editing, and tr The `useDemo` hook extends `useCode` functionality to provide a complete demo rendering solution that combines component previews with code display. It's specifically designed for creating interactive demonstrations where users can see both working React components and their source code. -
+
Outline @@ -169,7 +169,7 @@ The `useDemo` hook extends `useCode` functionality to provide a complete demo re The `useSearch` hook provides a powerful client-side search engine using [Orama](https://github.com/oramasearch/orama) for documentation sites. It handles index creation, search queries, and result formatting with built-in support for stemming, grouping, faceting, and customizable result types. -
+
Outline @@ -209,7 +209,7 @@ The `useSearch` hook provides a powerful client-side search engine using [Orama] Access processed type information within a `TypesTable` component using the [Props Context Layering](../../patterns/props-context-layering/page.mdx) pattern. -
+
Outline @@ -236,7 +236,7 @@ Access processed type information within a `TypesTable` component using the [Pro Look up individual type data by name from the nearest `TypesDataProvider`. -
+
Outline @@ -276,7 +276,7 @@ Look up individual type data by name from the nearest `TypesDataProvider`. The `usePreference` hook provides specialized preference management for code demo variants and transformations. It builds on `useLocalStorageState` with intelligent storage key generation, prefix support, and automatic optimization for single-option scenarios. -
+
Outline @@ -310,7 +310,7 @@ The `usePreference` hook provides specialized preference management for code dem The `useUrlHashState` hook provides a simple way to synchronize component state with the URL hash fragment, enabling deep linking, state persistence, and browser navigation support in documentation and demo pages. -
+
Outline @@ -340,7 +340,7 @@ The `useUrlHashState` hook provides a simple way to synchronize component state The `useLocalStorageState` hook provides persistent state management using localStorage with cross-tab synchronization, server-side rendering support, and a useState-like API. It's designed for user preferences, demo state, and any data that should persist across browser sessions. -
+
Outline @@ -376,7 +376,7 @@ The `useLocalStorageState` hook provides persistent state management using local The `useCopier` hook provides robust clipboard copy functionality with success state management, error handling, and customizable callbacks. It's designed for code blocks, buttons, and interactive elements that need copy-to-clipboard functionality. -
+
Outline @@ -406,7 +406,7 @@ The `useCopier` hook provides robust clipboard copy functionality with success s The `useErrors` hook provides access to error state in an isomorphic error handling system. It implements the [Props Context Layering pattern](../../patterns/props-context-layering/page.mdx) to work seamlessly across server and client boundaries, making it ideal for code highlighting and interactive demos that need robust error handling. -
+
Outline diff --git a/docs/app/docs-infra/hooks/use-types/demos/page.mdx b/docs/app/docs-infra/hooks/use-types/demos/page.mdx index 39a072286..ed0f573ec 100644 --- a/docs/app/docs-infra/hooks/use-types/demos/page.mdx +++ b/docs/app/docs-infra/hooks/use-types/demos/page.mdx @@ -17,7 +17,7 @@ No description available -
+
Outline @@ -33,7 +33,7 @@ No description available No description available -
+
Outline @@ -48,7 +48,7 @@ No description available No description available -
+
Outline @@ -65,7 +65,7 @@ No description available No description available -
+
Outline @@ -83,7 +83,7 @@ No description available No description available -
+
Outline @@ -104,7 +104,7 @@ No description available No description available -
+
Outline @@ -123,7 +123,7 @@ No description available No description available -
+
Outline @@ -139,7 +139,7 @@ No description available No description available -
+
Outline diff --git a/docs/app/docs-infra/overview/page.mdx b/docs/app/docs-infra/overview/page.mdx index 63ebd1c3f..066c76dcf 100644 --- a/docs/app/docs-infra/overview/page.mdx +++ b/docs/app/docs-infra/overview/page.mdx @@ -13,7 +13,7 @@ This page explains the overall architecture of `@mui/internal-docs-infra`, including data flows, key design decisions, and how the various pieces fit together. -
+
Outline @@ -43,7 +43,7 @@ This page explains the overall architecture of `@mui/internal-docs-infra`, inclu This guide covers how to set up your development environment and contribute to `@mui/internal-docs-infra`. -
+
Outline diff --git a/docs/app/docs-infra/patterns/page.mdx b/docs/app/docs-infra/patterns/page.mdx index 041a0d839..6ca62267b 100644 --- a/docs/app/docs-infra/patterns/page.mdx +++ b/docs/app/docs-infra/patterns/page.mdx @@ -14,7 +14,7 @@ At its core, a factory only needs a URL. In TypeScript we can rely on `import.meta.url` as the starting point for any operation. -
+
Outline @@ -36,7 +36,7 @@ At its core, a factory only needs a URL. In TypeScript we can rely on `import.me **Purpose**: Enable isomorphic components to work seamlessly with React Server Components while maintaining a single, ergonomic API. -
+
Outline @@ -57,7 +57,7 @@ At its core, a factory only needs a URL. In TypeScript we can rely on `import.me HAST is the core data structure used throughout this package for syntax highlighting and markdown processing. Understanding HAST helps you work effectively with the docs infra. -
+
Outline diff --git a/docs/app/docs-infra/pipeline/page.mdx b/docs/app/docs-infra/pipeline/page.mdx index 5cbfc386a..fb6545c2b 100644 --- a/docs/app/docs-infra/pipeline/page.mdx +++ b/docs/app/docs-infra/pipeline/page.mdx @@ -40,7 +40,7 @@ The `enhanceCodeEmphasis` source enhancer adds visual emphasis to specific lines in code examples by marking them with a `data-hl` attribute. This allows you to highlight important code patterns or call attention to specific sections in demos using simple comment annotations. -
+
Outline @@ -107,7 +107,7 @@ The `enhanceCodeEmphasis` source enhancer adds visual emphasis to specific lines A rehype plugin that improves the visual appearance of inline `` elements by consolidating HTML tag brackets into styled spans, reclassifying misidentified tokens, and applying nullish value classes. -
+
Outline @@ -146,7 +146,7 @@ A rehype plugin that improves the visual appearance of inline `` elements A rehype plugin that transforms code identifiers into clickable links, allowing users to navigate to type documentation by clicking on type references in code snippets. -
+
Outline @@ -276,7 +276,7 @@ A rehype plugin that transforms code identifiers into clickable links, allowing The `hastUtils` module provides utilities for converting between HAST (Hypertext Abstract Syntax Tree) nodes, strings, and React JSX elements. These utilities are essential for processing syntax-highlighted code and converting markdown/HTML structures to React components. -
+
Outline @@ -308,7 +308,7 @@ The `hastUtils` module provides utilities for converting between HAST (Hypertext The `loadCodeVariant` module provides utilities for loading, processing, and transforming code variants with support for syntax highlighting, TypeScript-to-JavaScript transformation, extra files, and metadata management. -
+
Outline @@ -392,7 +392,7 @@ The `loadCodeVariant` module provides utilities for loading, processing, and tra The precompute loader is a Webpack/Turbopack loader that enables build-time optimization of code examples by processing demo files and precomputing syntax highlighting, TypeScript transformations, and dependency resolution. -
+
Outline @@ -440,7 +440,7 @@ The precompute loader is a Webpack/Turbopack loader that enables build-time opti The precomputed code client loader is a Webpack/Turbopack loader that enables build-time optimization of client-side demo components by processing demo client files and precomputing external dependencies for live editing environments. -
+
Outline @@ -486,7 +486,7 @@ The precomputed code client loader is a Webpack/Turbopack loader that enables bu The precomputed sitemap loader is a Webpack/Turbopack loader that processes markdown files at build time to create optimized search indexes and navigation data. It extracts metadata from documentation pages and generates structured sitemap data with Orama search schema. -
+
Outline @@ -538,7 +538,7 @@ The precomputed sitemap loader is a Webpack/Turbopack loader that processes mark The precomputed types loader is a Webpack/Turbopack loader that automatically generates comprehensive type documentation for your TypeScript components at build time. Write your components in TypeScript, and the loader extracts props, methods, and type signatures—ready to display in your documentation. -
+
Outline @@ -577,7 +577,7 @@ The precomputed types loader is a Webpack/Turbopack loader that automatically ge The `loadServerCodeMeta` utility parses demo files to extract variant information and resolves file paths for code metadata. It reads demo index files, finds `createDemo` factory calls, and builds a `Code` object mapping variant names to their file URLs. -
+
Outline @@ -619,7 +619,7 @@ The `loadServerCodeMeta` utility parses demo files to extract variant informatio The `loadServerPageIndex` utility reads a markdown file and extracts page metadata for use in sitemaps. It parses the markdown content, extracts titles, descriptions, sections, and keywords, and derives additional metadata like URL prefix from the file path. -
+
Outline @@ -667,7 +667,7 @@ The `loadServerPageIndex` utility reads a markdown file and extracts page metada The `loadServerSitemap` utility parses sitemap index files to load page metadata at runtime. It reads the sitemap index file, finds [`createSitemap`](../../factories/create-sitemap/page.mdx) factory calls, resolves page imports, and builds a complete `Sitemap` object with schema and data. -
+
Outline @@ -703,7 +703,7 @@ The `loadServerSitemap` utility parses sitemap index files to load page metadata The `loadServerSource` utility reads source files from the filesystem and analyzes their dependencies, extracting imports and resolving relative file paths. It processes JavaScript/TypeScript files to build dependency trees and prepare code for documentation and live demos. -
+
Outline @@ -742,7 +742,7 @@ The `loadServerSource` utility reads source files from the filesystem and analyz A server-side function for loading and processing TypeScript types with syntax highlighting. This function coordinates the type extraction pipeline and applies HAST transformations for rendering. -
+
Outline @@ -781,7 +781,7 @@ A server-side function for loading and processing TypeScript types with syntax h The core server-side function for loading and formatting TypeScript type metadata. This function extracts types from your source files and returns structured data ready for documentation generation or rendering. -
+
Outline @@ -827,7 +827,7 @@ The core server-side function for loading and formatting TypeScript type metadat A function for parsing `types.md` files back into structured type metadata. This is the reverse operation of [`syncTypes`](../sync-types/page.mdx) — it reads markdown and reconstructs organized type exports. -
+
Outline @@ -855,7 +855,7 @@ A function for parsing `types.md` files back into structured type metadata. This The loader utilities provide a comprehensive set of functions for resolving, parsing, and processing import statements in JavaScript/TypeScript code. These utilities are essential for building systems that need to analyze and transform code imports, such as code highlighters, bundlers, and documentation generators. -
+
Outline @@ -938,7 +938,7 @@ The loader utilities provide a comprehensive set of functions for resolving, par The `parseSource` utility parses source code into HAST (Hypertext Abstract Syntax Tree) nodes with syntax highlighting using [Starry Night](https://github.com/wooorm/starry-night). It converts code into highlighted HTML structures for display in documentation and demos. -
+
Outline @@ -979,7 +979,7 @@ The `parseSource` utility parses source code into HAST (Hypertext Abstract Synta The `syncPageIndex` function automatically maintains index pages by extracting metadata from documentation pages and updating parent directory indexes. It's designed to work with Next.js file-based routing, keeping navigation indexes in sync as pages are added or modified. -
+
Outline @@ -1021,7 +1021,7 @@ The `syncPageIndex` function automatically maintains index pages by extracting m The server-side function for synchronizing TypeScript type documentation to disk. This function coordinates type loading and markdown generation, updating the `types.md` file and optionally the parent index page. -
+
Outline @@ -1049,7 +1049,7 @@ The server-side function for synchronizing TypeScript type documentation to disk A rehype plugin that transforms `
` elements containing `` blocks into precomputed data for the CodeHighlighter component. This plugin extracts source code from HTML, processes it through syntax highlighting and transformations, then stores the results for efficient client-side rendering.
 
-
+
Outline @@ -1081,7 +1081,7 @@ A rehype plugin that transforms `
` elements containing `` blocks into
 
 A rehype plugin that applies lightweight syntax highlighting to inline `` elements without adding line gutters, frame wrappers, or precomputed data attributes.
 
-
+
Outline @@ -1138,7 +1138,7 @@ A rehype plugin that applies lightweight syntax highlighting to inline `` The `transformMarkdownBlockquoteCallouts` plugin is a Remark plugin that enables GitHub-style callout blocks in markdown. It transforms blockquotes with special markers (like `> [!NOTE]`) into HTML blockquotes with a `data-callout-type` attribute, making it easy to style and render callouts in your documentation. -
+
Outline @@ -1162,7 +1162,7 @@ The `transformMarkdownBlockquoteCallouts` plugin is a Remark plugin that enables A remark plugin that transforms markdown code blocks into HTML structures with enhanced metadata support. This plugin handles both individual code blocks with options and multi-variant code examples. It's the **first stage** in a processing pipeline, typically followed by [`transformHtmlCodeBlock`](../transform-html-code-block/page.mdx) for final rendering. -
+
Outline @@ -1215,7 +1215,7 @@ A remark plugin that transforms markdown code blocks into HTML structures with e A remark plugin that automatically cleans up meta links ("[See Demo]", "[See Setup]", "[See Types]") and horizontal rules that follow Demo and Types components in markdown documentation. This plugin identifies these components (without `.Title`) and removes associated navigation elements to create cleaner documentation. -
+
Outline @@ -1254,7 +1254,7 @@ A remark plugin that automatically cleans up meta links ("[See Demo]", "[See Set A remark plugin that extracts metadata from MDX files and optionally updates parent directory index pages. This plugin automatically collects page titles, descriptions, keywords, and hierarchical section structures to create searchable, navigable documentation indexes. -
+
Outline @@ -1320,7 +1320,7 @@ A remark plugin that extracts metadata from MDX files and optionally updates par The `transformMarkdownRelativePaths` plugin is a Remark plugin that automatically transforms relative markdown links to work seamlessly in both development environments (VSCode, GitHub) and production builds. It strips page file extensions and converts relative paths to absolute URLs. -
+
Outline @@ -1355,7 +1355,7 @@ The `transformMarkdownRelativePaths` plugin is a Remark plugin that automaticall The `transformTypescriptToJavascript` utility transforms TypeScript/TSX code into JavaScript/JSX using Babel, preserving formatting and automatically generating JavaScript variants for documentation and demos. -
+
Outline @@ -1382,7 +1382,7 @@ The `transformTypescriptToJavascript` utility transforms TypeScript/TSX code int The `withDocsInfra` function is a Next.js configuration plugin that sets up webpack loaders, Turbopack rules, and page extensions required for MUI docs infrastructure. It automatically configures code highlighting loaders for demo files and provides sensible defaults for documentation sites. -
+
Outline diff --git a/docs/app/docs-infra/pipeline/sync-page-index/page.mdx b/docs/app/docs-infra/pipeline/sync-page-index/page.mdx index 19cea7180..bbcef8a2e 100644 --- a/docs/app/docs-infra/pipeline/sync-page-index/page.mdx +++ b/docs/app/docs-infra/pipeline/sync-page-index/page.mdx @@ -134,7 +134,7 @@ The function generates markdown with a specific structure: A clickable button component. -
+
Outline - Sections: diff --git a/packages/docs-infra/src/pipeline/syncPageIndex/mergeMetadataMarkdown.test.ts b/packages/docs-infra/src/pipeline/syncPageIndex/mergeMetadataMarkdown.test.ts index f321f662d..287d5843b 100644 --- a/packages/docs-infra/src/pipeline/syncPageIndex/mergeMetadataMarkdown.test.ts +++ b/packages/docs-infra/src/pipeline/syncPageIndex/mergeMetadataMarkdown.test.ts @@ -465,7 +465,7 @@ Old description. ![Button preview](https://example.com/button.png) -
+
Outline @@ -798,7 +798,7 @@ Old checkbox description. A tooltip component. -
+
Outline diff --git a/packages/docs-infra/src/pipeline/syncPageIndex/metadataToMarkdown.test.ts b/packages/docs-infra/src/pipeline/syncPageIndex/metadataToMarkdown.test.ts index 5ed48c42d..c9adc5af6 100644 --- a/packages/docs-infra/src/pipeline/syncPageIndex/metadataToMarkdown.test.ts +++ b/packages/docs-infra/src/pipeline/syncPageIndex/metadataToMarkdown.test.ts @@ -43,7 +43,7 @@ describe('metadataToMarkdown', () => { ![A simple button](https://example.com/button.png) -
+
Outline diff --git a/packages/docs-infra/src/pipeline/syncPageIndex/metadataToMarkdown.ts b/packages/docs-infra/src/pipeline/syncPageIndex/metadataToMarkdown.ts index b6753cf7c..679fe89e3 100644 --- a/packages/docs-infra/src/pipeline/syncPageIndex/metadataToMarkdown.ts +++ b/packages/docs-infra/src/pipeline/syncPageIndex/metadataToMarkdown.ts @@ -973,9 +973,12 @@ export function metadataToMarkdownAst( } // Wrap metadata in details/summary tags + const detailsPath = page.path.endsWith('/page.mdx') + ? page.path.substring(0, page.path.length - '/page.mdx'.length) + : page.path; children.push({ type: 'html', - value: '
', + value: `
`, } as any); children.push(paragraph('')); children.push({ @@ -1175,7 +1178,10 @@ export function metadataToMarkdown( let hasMetadataContent = false; if (hasKeywords || hasSections || hasParts || hasExports || hasTypes) { - lines.push('
'); + const detailsPath = page.path.endsWith('/page.mdx') + ? page.path.substring(0, page.path.length - '/page.mdx'.length) + : page.path; + lines.push(`
`); lines.push(''); lines.push('Outline'); lines.push(''); diff --git a/packages/docs-infra/src/pipeline/syncPageIndex/syncPageIndex.test.ts b/packages/docs-infra/src/pipeline/syncPageIndex/syncPageIndex.test.ts index 9d762f390..269669e0e 100644 --- a/packages/docs-infra/src/pipeline/syncPageIndex/syncPageIndex.test.ts +++ b/packages/docs-infra/src/pipeline/syncPageIndex/syncPageIndex.test.ts @@ -274,7 +274,7 @@ Old description. ![Button preview](https://example.com/button.png) -
+
Outline @@ -873,7 +873,7 @@ An input component. An alert dialog component. -
+
Outline @@ -946,7 +946,7 @@ An input component. A tooltip component. -
+
Outline @@ -1032,7 +1032,7 @@ A button component. A button component. -
+
Outline @@ -1113,7 +1113,7 @@ A button component. A checkbox component. -
+
Outline @@ -1130,7 +1130,7 @@ A button component. A switch component. -
+
Outline diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 10b92bfda..da55d7ed3 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -3016,7 +3016,7 @@ packages: '@mui/base@5.0.0-beta.69': resolution: {integrity: sha512-r2YyGUXpZxj8rLAlbjp1x2BnMERTZ/dMqd9cClKj2OJ7ALAuiv/9X5E9eHfRc9o/dGRuLSMq/WTjREktJVjxVA==} engines: {node: '>=14.0.0'} - deprecated: This package has been replaced by @base-ui/react + deprecated: This package has been replaced by @base-ui-components/react peerDependencies: '@types/react': ^17.0.0 || ^18.0.0 || ^19.0.0 react: ^17.0.0 || ^18.0.0 || ^19.0.0