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

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)

Types

loadServerSitemap

loadServerSitemap

Default loadServerSitemap function that loads sitemap data from a sitemap index file. This function parses the sitemap index file to find createSitemap calls and resolves the page index paths from the imports.

ParameterTypeDescription
urlstring
Return Type
Promise<Sitemap>

createLoadServerSitemap

createLoadServerSitemap

Creates a loadServerSitemap function with custom options.

This factory function creates a LoadServerSitemap implementation that:

  1. Parses the sitemap index file to find createSitemap calls with page imports
  2. Resolves all page index paths from the imports
  3. Loads each page index using loadServerPageIndex
  4. Returns a Sitemap object with schema and page data
ParameterTypeDescription
optionsCreateLoadServerSitemapOptions | undefined

Configuration options for the loader

Return Type
((url: string) => Promise<Sitemap>)

LoadServerSitemap function that takes a file URL and returns Promise

createSitemapSchema

createSitemapSchema

Creates the default Orama schema for search indexing. See: https://docs.orama.com/docs/orama-js/usage/create#schema-properties-and-types

Return Type
Record<string, OramaSchemaType>

Additional Types

CreateLoadServerSitemapOptions

Options for creating a loadServerSitemap function

type CreateLoadServerSitemapOptions = { rootContext?: string };

Related