MUI Docs Infra

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

API Reference

loadServerPageIndex

function loadServerPageIndex(filePath: string): Promise<SitemapSectionData | null>;

Loads page metadata from a markdown file using the default root context (process.cwd()).

Parameters:

ParameterTypeDescription
filePathstringFile URL (file://) or absolute path to the markdown file

Returns: Promise resolving to SitemapSectionData or null if parsing fails.

Throws: Error if the file cannot be read.

createLoadServerPageIndex

function createLoadServerPageIndex(options?: CreateLoadServerPageIndexOptions): LoadServerPageIndex;

Creates a custom loadServerPageIndex function with specific options.

Parameters:

ParameterTypeDefaultDescription
options.rootContextstringprocess.cwd()Root directory for resolving relative paths

Returns: A LoadServerPageIndex function.

pathSegmentToTitle

function pathSegmentToTitle(segment: string): string;

Converts a kebab-case path segment to Title Case.

Parameters:

ParameterTypeDescription
segmentstringPath segment to convert

Returns: Title-cased string.

extractPrefixAndTitle

function extractPrefixAndTitle(
  absolutePath: string,
  rootContext: string,
): { prefix: string; title: string };

Extracts URL prefix and section title from a file path.

Parameters:

ParameterTypeDescription
absolutePathstringAbsolute path to the markdown file
rootContextstringRoot directory for relative paths

Returns: Object with prefix (URL path) and title (human-readable).

stripTitleMarkdown

function stripTitleMarkdown(hierarchy: HeadingHierarchy): Record<string, SitemapSection>;

Recursively removes titleMarkdown AST fields from a heading hierarchy to reduce bundle size.

Parameters:

ParameterTypeDescription
hierarchyHeadingHierarchyHeading hierarchy with AST nodes

Returns: Cleaned hierarchy without markdown AST nodes.

Type Definitions

SitemapSectionData

interface SitemapSectionData {
  title: string;
  prefix: string;
  pages: SitemapPage[];
}

SitemapPage

interface SitemapPage {
  slug: string;
  path: string;
  title: string;
  description?: string;
  keywords?: string[];
  sections?: Record<string, SitemapSection>;
}

SitemapSection

interface SitemapSection {
  title: string;
  children?: Record<string, SitemapSection>;
}

CreateLoadServerPageIndexOptions

interface CreateLoadServerPageIndexOptions {
  /**
   * The root context directory for resolving relative paths.
   * Defaults to process.cwd().
   */
  rootContext?: string;
}

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
    }
  }
}

Related