MUI Docs Infra

Create Sitemap

The createSitemap factory function defines sitemap data for documentation sites. It works with the webpack loader for build-time precomputation in Next.js builds.

Overview

Tip

Place your sitemap at app/sitemap/index.ts for automatic detection by withDocsInfra.

import { createSitemap } from '@mui/internal-docs-infra/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,
});

During Next.js builds, the loadPrecomputedSitemap webpack loader processes this file and precomputes the sitemap data. Outside Next.js, use loadServerSitemap for runtime loading.

API Reference

function createSitemap(
  sourceUrl: string,
  pages: Record<string, React.ComponentType>,
  meta?: CreateSitemapMeta,
): Sitemap | undefined;

Creates sitemap data from page components with optional precomputed data.

Parameters

ParameterTypeDescription
sourceUrlstringFile URL from import.meta.url
pagesRecord<string, React.ComponentType>Record of page components indexed by key
metaCreateSitemapMetaOptional configuration and precomputed data

Returns

  • In Next.js builds: Sitemap object with schema and precomputed page data
  • Outside Next.js: undefined (use loadServerSitemap instead)

Behavior

  1. With precomputed data (meta.precompute): Returns the precomputed sitemap directly
  2. In Next.js context: Throws an error if precomputation didn't happen (configuration issue)
  3. Outside Next.js: Returns undefined for graceful fallback

Runtime Loading

For loading sitemap data outside of Next.js builds (e.g., in tests, scripts, or non-Next.js applications), use loadServerSitemap:

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

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

// sitemap.schema contains the Orama schema
// sitemap.data contains all page metadata organized by section

File Structure

The sitemap index file should be placed at app/sitemap/index.ts:

app/
├── sitemap/
│   └── index.ts              ← Sitemap definition
├── docs-infra/
│   ├── components/
│   │   └── page.mdx          ← Section index
│   └── functions/
│       └── page.mdx          ← Section index

Each imported page component should be a markdown file that serves as a section index (e.g., components/page.mdx lists all components).

Type Definitions

CreateSitemapMeta

interface CreateSitemapMeta {
  name?: string;
  slug?: string;
  displayName?: string;
  precompute?: Sitemap; // Injected by webpack loader
  skipPrecompute?: boolean; // Disable precomputation
}

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

Configuration

Skip Precomputation

Disable precomputation for development or testing:

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

Webpack Loader Setup

The webpack loader must be configured for the sitemap index file. See withDocsInfra or loadPrecomputedSitemap for configuration details.

Integration with Search

The sitemap data is designed for use 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:///path/to/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]) =>
  section.pages.map((page) => ({
    ...page,
    section: section.title,
    prefix: section.prefix,
  })),
);

await insertMultiple(searchIndex, pages);

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

Populating the Sitemap

The sitemap's page data (titles, descriptions, sections, keywords) comes from metadata exported by each MDX page. Use the transformMarkdownMetadata remark plugin to automatically extract this metadata:

// Each MDX page exports metadata like:
export const metadata = {
  title: 'Button',
  description: 'A clickable button component.',
  keywords: ['button', 'click', 'action'],
};

The plugin extracts:

  • Title from the first H1 heading
  • Description from the first paragraph
  • Sections from the heading hierarchy (H2-H6)
  • Keywords from the metadata export

See transformMarkdownMetadata for configuration options and automatic index generation.

Related