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 Sitemap

The loadServerSitemap utility parses sitemap index files to load page metadata at runtime. It reads the sitemap index file, finds createSitemap factory calls, resolves page imports, and builds a complete Sitemap object with schema and data.

Tip

Use this function for runtime loading outside of Next.js builds (e.g., in tests, scripts, or non-Next.js applications).

Basic Usage

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

// Load sitemap from a sitemap index file
const sitemap = await loadServerSitemap('file:///app/sitemap/index.ts');

// Returns: { schema: {...}, data: { DocsInfraComponents: {...}, DocsInfraFunctions: {...} } }

The function:

  • Reads the sitemap index file
  • Finds the createSitemap() call and extracts page imports
  • Resolves each page import path to absolute file paths
  • Loads each page's markdown file and extracts metadata
  • Returns a Sitemap object with schema and data

Common Patterns

Loading from Sitemap Index

Given a sitemap index file:

// app/sitemap/index.ts
import { createSitemap } from '../functions/createSitemap';
import DocsInfraComponents from '../docs-infra/components/page.mdx';
import DocsInfraFunctions from '../docs-infra/functions/page.mdx';

export const sitemap = createSitemap(import.meta.url, {
  DocsInfraComponents,
  DocsInfraFunctions,
});

You can load it at runtime:

const sitemap = await loadServerSitemap('file:///path/to/app/sitemap/index.ts');

// Returns:
// {
//   schema: {
//     slug: 'string',
//     path: 'string',
//     title: 'string',
//     description: 'string',
//     sections: 'string[]',
//     subsections: 'string[]',
//     keywords: 'string[]',
//   },
//   data: {
//     DocsInfraComponents: {
//       title: 'Docs Infra Components',
//       prefix: '/docs-infra/components/',
//       pages: [...]
//     },
//     DocsInfraFunctions: {
//       title: 'Docs Infra Functions',
//       prefix: '/docs-infra/functions/',
//       pages: [...]
//     }
//   }
// }

Advanced Usage

Custom Implementation

Create a custom loadServerSitemap function using the factory:

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

const customLoadSitemap = createLoadServerSitemap({
  // Override the root context for resolving relative paths
  rootContext: '/custom/root/path',
});

const sitemap = await customLoadSitemap('file:///path/to/sitemap/index.ts');

Integration with Search

Using with Orama search:

import { create, insertMultiple, search } from '@orama/orama';
import { loadServerSitemap } from '@mui/internal-docs-infra/pipeline/loadServerSitemap';

// Load the sitemap at runtime
const sitemap = await loadServerSitemap('file:///app/sitemap/index.ts');

// Create search index with the schema
const searchIndex = await create({
  schema: sitemap.schema,
});

// Flatten and insert pages
const pages = Object.entries(sitemap.data).flatMap(([_key, section]) => {
  return section.pages.map((page) => ({
    ...page,
    section: section.title,
    prefix: section.prefix,
  }));
});

await insertMultiple(searchIndex, pages);

// Search
const results = await search(searchIndex, { term: 'code' });

API Reference

loadServerSitemap

function loadServerSitemap(url: string): Promise<Sitemap>;

Loads sitemap data by parsing a sitemap index file.

Parameters:

ParameterTypeDescription
urlstringFile URL to the sitemap index file (with file://)

Returns: Promise resolving to a Sitemap object with schema and page data.

Throws:

  • Error if the sitemap index file cannot be read or parsed
  • Error if any page index files fail to load (lists all failures)

createLoadServerSitemap

function createLoadServerSitemap(options?: CreateLoadServerSitemapOptions): LoadServerSitemap;

Creates a custom loadServerSitemap function with specific options.

Parameters:

ParameterTypeDefaultDescription
options.rootContextstringDirectory of URL fileRoot directory for resolving relative paths

Returns: A LoadServerSitemap function.

createSitemapSchema

function createSitemapSchema(): Sitemap['schema'];

Creates the default Orama-compatible schema for search indexing.

Returns: Schema object with field type definitions.

{
  slug: 'string',
  path: 'string',
  title: 'string',
  description: 'string',
  sections: 'string[]',
  subsections: 'string[]',
  keywords: 'string[]',
}

Type Definitions

Sitemap

interface Sitemap {
  schema: {
    slug: 'string';
    path: 'string';
    title: 'string';
    description: 'string';
    sections: 'string[]';
    subsections: 'string[]';
    keywords: 'string[]';
  };
  data: Record<string, SitemapSectionData>;
}

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

Comparison: Build-Time vs Runtime

FeatureBuild-Time (Webpack Loader)Runtime (loadServerSitemap)
When processedDuring Next.js buildAt runtime when called
CachingWebpack dependency cacheManual caching via Map
EnvironmentNext.js onlyAny Node.js environment
Use caseProduction buildsTests, scripts, non-Next.js apps
PerformanceFastest (precomputed)Slower (reads files at runtime)

Related