MUI Docs Infra

Warning

This is an internal project, and is not intended for public use. No support or stability guarantees are provided.

Load Server Page Index

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.

Note

This function is primarily used internally by loadServerSitemap to process individual page files. Most users won't need to call it directly.

Basic Usage

import { loadServerPageIndex } from '@mui/internal-docs-infra/pipeline/loadServerPageIndex';

// Load metadata from a markdown file
const pageData = await loadServerPageIndex('file:///path/to/docs-infra/components/page.mdx');

// Returns: { title: 'Docs Infra Components', prefix: '/docs-infra/components/', pages: [...] }

The function:

  • Reads the markdown file content
  • Parses it using markdownToMetadata to extract page data
  • Derives URL prefix and section title from the file path
  • Strips unnecessary AST nodes to reduce size
  • Returns a SitemapSectionData object

Common Patterns

Loading a Single Page Index

import { loadServerPageIndex } from '@mui/internal-docs-infra/pipeline/loadServerPageIndex';

const data = await loadServerPageIndex('file:///app/docs-infra/functions/page.mdx');

// Returns:
// {
//   title: 'Docs Infra Functions',
//   prefix: '/docs-infra/functions/',
//   pages: [
//     {
//       slug: 'load-server-code-meta',
//       path: './load-server-code-meta/page.mdx',
//       title: 'Load Server Code Meta',
//       description: 'Parses demo files to extract variant information...',
//       keywords: ['code', 'meta', 'demo'],
//       sections: { ... }
//     },
//     // ... more pages
//   ]
// }

With Custom Root Context

When your files are not at the default location:

import { createLoadServerPageIndex } from '@mui/internal-docs-infra/pipeline/loadServerPageIndex';

const loadPageIndex = createLoadServerPageIndex({
  rootContext: '/custom/docs/root',
});

const data = await loadPageIndex('file:///custom/docs/root/components/page.mdx');
// prefix will be '/components/' instead of the full path

Path Processing

The loader automatically processes file paths to generate useful metadata.

Path Segment to Title

Converts kebab-case path segments to Title Case:

import { pathSegmentToTitle } from '@mui/internal-docs-infra/pipeline/loadServerPageIndex';

pathSegmentToTitle('docs-infra'); // 'Docs Infra'
pathSegmentToTitle('code-highlighter'); // 'Code Highlighter'
pathSegmentToTitle('abstract-create-demo'); // 'Abstract Create Demo'

URL Prefix Generation

The extractPrefixAndTitle function generates URL prefixes from directory structure:

import { extractPrefixAndTitle } from '@mui/internal-docs-infra/pipeline/loadServerPageIndex';

extractPrefixAndTitle('/app/docs-infra/components/page.mdx', '/app');
// { prefix: '/docs-infra/components/', title: 'Docs Infra Components' }

extractPrefixAndTitle('/app/(public)/blog/page.mdx', '/app');
// { prefix: '/blog/', title: 'Blog' }  (route groups are removed)

extractPrefixAndTitle('/src/app/page.mdx', '/src/app');
// { prefix: '/', title: '' }

Note

extractPrefixAndTitle expects absolute file paths (without file:// prefix), not file URLs.

Filtered Path Segments

The following are automatically removed from paths:

  • src - Only if at the start
  • app - Only if at the start (or after src)
  • Route groups - Segments in parentheses like (public), (content)
  • Empty segments - Including . and empty strings

Data Optimization

The loader automatically optimizes the metadata to reduce bundle size:

Stripped Fields

  • descriptionMarkdown - Raw markdown AST for descriptions (can be 50%+ of size)
  • titleMarkdown - Raw markdown AST for section titles

Normalized Fields

  • children: {} - Empty children objects are converted to undefined

Example Output

Before optimization:

{
  sections: {
    features: {
      title: 'Features',
      titleMarkdown: { type: 'root', children: [...] },  // Removed
      children: {}  // Converted to undefined
    }
  },
  descriptionMarkdown: { type: 'root', children: [...] }  // Removed
}

After optimization:

{
  sections: {
    features: {
      title: 'Features',
      children: undefined
    }
  }
}

Types

loadServerPageIndex

loadServerPageIndex

Default loadServerPageIndex function that loads page index data from a markdown file. This function uses process.cwd() as the root context for resolving relative paths.

ParameterTypeDescription
filePathstring
Return Type
Promise<SitemapSectionData | null>

createLoadServerPageIndex

createLoadServerPageIndex

Creates a loadServerPageIndex function with custom options.

This factory function creates a LoadServerPageIndex implementation that:

  1. Reads the markdown file from the provided file path
  2. Parses the markdown to extract metadata using markdownToMetadata
  3. Enriches the metadata with prefix and title derived from the file path
  4. Returns a SitemapSectionData object with page data
ParameterTypeDescription
optionsCreateLoadServerPageIndexOptions | undefined

Configuration options for the loader

Return Type
((filePath: string) => Promise<SitemapSectionData | null>)

LoadServerPageIndex function that takes a file path and returns Promise<SitemapSectionData | null>

extractPrefixAndTitle

extractPrefixAndTitle

Extracts prefix and title from an import path e.g., “/path/to/app/docs-infra/components/page.mdx” -> { prefix: “/docs-infra/components/", title: “Docs Infra Components” }

ParameterTypeDescription
absolutePathstring
rootContextstring
Return Type
KeyTypeDescription
prefixstring
titlestring

pathSegmentToTitle

pathSegmentToTitle

Converts a path segment to a title e.g., “docs-infra” -> “Docs Infra”, “components” -> “Components”

ParameterTypeDescription
segmentstring
Return Type
string

stripTitleMarkdown

stripTitleMarkdown

Recursively removes titleMarkdown fields from a heading hierarchy

ParameterTypeDescription
hierarchy{ [slug: string]: { title: string; titleMarkdown: PhrasingContent[]; children: HeadingHierarchy } }
Return Type
Record<string, SitemapSection>

Additional Types

CreateLoadServerPageIndexOptions

Options for creating a loadServerPageIndex function

type CreateLoadServerPageIndexOptions = { rootContext?: string };

Related