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.

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.

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

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).

string

Record<string, React.ComponentType<any> | null>

CreateSitemapMeta | undefined

Sitemap | undefined

type Audience = 'private' | 'introductory' | 'intermediate' | 'advanced' | 'business'

type NextMetadata = Metadata & { other?: { [key: string]: unknown; audience?: Audience } }

type OramaSchemaType =
  'string' | 'number' | 'boolean' | 'string[]' | 'number[]' | 'boolean[]' | `vector[${number}]`

type PageIndexSection = {
  /** The route group this section collects (e.g. `(components)`). */
  group: string;
  /** The (human-editable) heading text shown for the section. */
  title: string;
  /** Heading depth for the section title. Defaults to 2 (`##`). */
  depth?: number;
}

type Sitemap = {
  schema: Record<string, OramaSchemaType>;
  data: Record<string, SitemapSectionData>;
}

type SitemapExport = { props?: string[]; dataAttributes?: string[]; cssVariables?: string[] }

type SitemapPage = {
  title?: string;
  slug: string;
  path: string;
  description?: string;
  keywords?: string[];
  sections?: Record<string, SitemapSection>;
  parts?: Record<string, SitemapPart>;
  exports?: Record<string, SitemapExport>;
  types?: string[];
  tags?: string[];
  skipDetailSection?: boolean;
  audience?: Audience;
  index?: boolean;
  /**
   * The title of the route-group section this page is listed under in a grouped index
   * (e.g. `Components`), resolved from the page's route group. `null` for a page in a flat
   * index or with no route group, so the field is always present. Useful for
   * grouping/faceting search results.
   */
  section: string | null;
  image?: { url: string; alt?: string };
}

type SitemapPart = {
  props?: string[];
  dataAttributes?: string[];
  cssVariables?: string[];
  parameters?: (string | string[])[];
  returns?: string[];
}

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

type SitemapSectionData = {
  title: string;
  prefix: string;
  pages: SitemapPage[];
  /**
   * Ordered route-group sections when the index is grouped (its `##` subtitles), so
   * search can recover the sections a page belongs to. An empty array for a flat index,
   * so the field is always present.
   */
  sections: PageIndexSection[];
  /** Heading of the detail-region wrapper in a grouped index (defaults to `Details`). */
  detailsSectionTitle?: string;
}

Disable precomputation for development or testing:

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

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

The sitemap data is designed for use with Orama search. For a ready-made React hook that handles index creation, querying, and result formatting, see useSearch.

Here's a lower-level example using Orama directly:

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

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 (or a user-overridden title if the list item was edited in the index. See syncPageIndex title overrides)
• 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.

Additional sitemap metadata is managed through the index files maintained by syncPageIndex. For example, in your index page.mdx:

- Button [New] - ([Outline](#button), [Contents](./button/page.mdx))
- Input - ([Outline](#text-field), [Contents](./text-field/page.mdx))

This shows:

• Tags: [New] is a lifecycle label that appears in the sitemap as page.tags. See syncPageIndex tags.
• Title overrides: "Input" overrides the page's actual H1 ("Text Field") for display in sitemaps and search. See syncPageIndex title overrides.
• Reordering: Button is listed before Input despite alphabetical order — syncPageIndex preserves manual ordering during updates.

• syncPageIndex - Maintain index pages with tags, title overrides, and ordering
• transformMarkdownMetadata - Extract metadata from MDX pages
• loadPrecomputedSitemap - Webpack loader for build-time processing
• loadServerSitemap - Runtime sitemap loading
• loadServerPageIndex - Loads individual page metadata
• withDocsInfra - Next.js plugin that configures the loader