MUI Docs Infra

Warning

This is an internal project, and is not intended for public use. No support or stability guarantees are provided.

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.

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

Types

createSitemap

Creates sitemap data from page components with optional precomputed data. Returns a sitemap data object containing schema and page data.

In Next.js builds, the webpack loader precomputes the sitemap data. Outside Next.js (e.g., tests or scripts), use loadServerSitemap() for runtime loading.

ParameterTypeDescription
sourceUrlstring

Depends on import.meta.url to determine the source file location.

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

Record of page components indexed by path.

metaCreateSitemapMeta | undefined

Additional meta and precomputed sitemap configuration.

Return Type
Sitemap | undefined

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