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

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