Skip to content

[docs-infra] Remove slugs from sitemap output #985

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dav-is wants to merge 3 commits into
base: master
Choose a base branch
from
Open

[docs-infra] Remove slugs from sitemap output #985

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
404f3b0
Remove slugs from sitemap output
dav-is Dec 17, 2025
8736300
Small fixes
dav-is Dec 17, 2025
469e572
Merge branch 'master' into docs-infra/remove-sitemap-index-slugs
dav-is Dec 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion docs/app/docs-infra/functions/create-sitemap/page.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -135,7 +135,6 @@ interface SitemapSectionData {

```ts
interface SitemapPage {
slug: string;
path: string;
title: string;
description?: string;
Expand Down
1 change: 0 additions & 1 deletion docs/app/docs-infra/functions/load-precomputed-sitemap/page.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -200,7 +200,6 @@ The loader generates a structured data format:
"prefix": "/docs-infra/components/",
"pages": [
{
"slug": "code-highlighter",
"path": "./code-highlighter/page.mdx",
"title": "Code Highlighter",
"description": "Component for displaying code...",
Expand Down
4 changes: 1 addition & 3 deletions docs/app/docs-infra/functions/load-server-page-index/page.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,6 @@ const data = await loadServerPageIndex('file:///app/docs-infra/functions/page.md
// prefix: '/docs-infra/functions/',
// pages: [
// {
// slug: 'load-server-code-meta',
// path: './load-server-code-meta/page.mdx',
// title: 'Load Server Code Meta',
// description: 'Parses demo files to extract variant information...',
Expand Down Expand Up @@ -223,9 +222,8 @@ interface SitemapSectionData {

```ts
interface SitemapPage {
slug: string;
path: string;
title: string;
path: string;
description?: string;
keywords?: string[];
sections?: Record<string, SitemapSection>;
Expand Down
1 change: 0 additions & 1 deletion docs/app/docs-infra/functions/load-server-sitemap/page.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -223,7 +223,6 @@ interface SitemapSectionData {

```ts
interface SitemapPage {
slug: string;
path: string;
title: string;
description?: string;
Expand Down
11 changes: 3 additions & 8 deletions docs/app/docs-infra/functions/sync-page-index/page.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,6 @@ import { syncPageIndex } from '@mui/internal-docs-infra/pipeline/syncPageIndex';
await syncPageIndex({
pagePath: './app/components/button/page.mdx',
metadata: {
slug: 'button',
path: './button/page.mdx',
title: 'Button',
description: 'A clickable button component.',
Expand All @@ -58,9 +57,9 @@ Update multiple pages in a single operation (more efficient with file locking):
await syncPageIndex({
pagePath: './app/components/page.mdx', // The index file itself
metadataList: [
{ slug: 'button', path: './button/page.mdx', title: 'Button', description: '...' },
{ slug: 'checkbox', path: './checkbox/page.mdx', title: 'Checkbox', description: '...' },
{ slug: 'dialog', path: './dialog/page.mdx', title: 'Dialog', description: '...' },
{ path: './button/page.mdx', title: 'Button', description: '...' },
{ path: './checkbox/page.mdx', title: 'Checkbox', description: '...' },
{ path: './dialog/page.mdx', title: 'Dialog', description: '...' },
],
});
```
Expand Down Expand Up @@ -187,7 +186,6 @@ Updates a parent directory's index file with page metadata.

```ts
interface PageMetadata {
slug: string; // URL slug (e.g., 'button')
path: string; // Relative path to MDX file
title: string; // Page title
description?: string; // Short description
Expand Down Expand Up @@ -220,7 +218,6 @@ Add status indicators that appear in the index list:
await syncPageIndex({
pagePath: './app/components/new-component/page.mdx',
metadata: {
slug: 'new-component',
path: './new-component/page.mdx',
title: 'New Component',
description: 'A brand new component.',
Expand All @@ -237,7 +234,6 @@ For components with API documentation, include `parts` or `exports` to make them
await syncPageIndex({
pagePath: './app/components/dialog/page.mdx',
metadata: {
slug: 'dialog',
path: './dialog/page.mdx',
title: 'Dialog',
description: 'A modal dialog component.',
Expand Down Expand Up @@ -265,7 +261,6 @@ For links to external resources, use `skipDetailSection`:
await syncPageIndex({
pagePath: './app/resources/page.mdx',
metadata: {
slug: 'github',
path: 'https://github.com/mui/base-ui',
title: 'GitHub',
tags: ['External'],
Expand Down
5 changes: 2 additions & 3 deletions docs/app/docs-infra/functions/transform-markdown-metadata/page.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -237,8 +237,7 @@ interface SitemapSectionData {
}

interface SitemapPage {
title?: string;
slug: string;
title: string;
path: string;
description?: string;
keywords?: string[];
Expand Down Expand Up @@ -673,7 +672,7 @@ To have pages automatically sorted alphabetically in your index, replace the def
- **User-controlled ordering**: Default marker `'This file is autogenerated, but the following list can be modified.'` preserves the order you define in the editable section
- **Automatic alphabetical**: Marker `'This file is autogenerated, but the following list can be modified. Automatically sorted alphabetically.'` sorts all pages alphabetically by title, ignoring the editable section order
- **Case-insensitive**: Sorting uses `localeCompare()` for natural alphabetical ordering
- **Fallback to slug**: If a page has no title, the slug is used for sorting
- **Title required**: Every page must have a title for sorting

This is useful for index pages where alphabetical order makes more sense than manual ordering, such as component libraries or API references.

Expand Down
8 changes: 6 additions & 2 deletions docs/app/docs-infra/hooks/use-search/page.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,6 @@ interface SitemapSectionData {

interface SitemapPage {
title: string;
slug: string;
path: string;
description: string;
keywords?: string[];
Expand Down Expand Up @@ -293,11 +292,16 @@ Override how pages are converted to search entries:
const { search } = useSearch({
sitemap: () => import('./sitemap'),
flattenPage: (page, sectionData) => {
const slug = page.title
Copy link
Member

@Janpot Janpot Dec 19, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Duplicate logic with https://github.com/mui/mui-public/pull/985/files#diff-19ec2058ffa4d961a1b2d87f221d2a1b5049e86d4b8e379acc0f71eedd26d1e9R27

What are the different use-cases and can we create a slug algorithm for each use case to be used by our docs?

  • markdown fragment to HTML id
  • ...?

Copy link
Member

@Janpot Janpot Jan 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

rehype-slug has en interesting position on the matter that slug generation should be universal.

.toLowerCase()
.replace(/[^a-z0-9]+/g, '-')
.replace(/^-+|-+$/g, '');

return [
{
type: 'page',
title: page.title,
slug: page.slug,
slug,
path: page.path,
description: page.description,
sectionTitle: sectionData.title,
Expand Down
3 changes: 1 addition & 2 deletions packages/docs-infra/src/createSitemap/types.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,8 +28,7 @@ export interface SitemapExport {
* Page data structure from sitemap
*/
export interface SitemapPage {
title?: string;
slug: string;
title: string;
path: string;
description?: string;
keywords?: string[];
Expand Down
Loading
Loading