[docs-infra] Remove slugs from sitemap output #985
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
dav-is
added
type: enhancement
Bundle size report
Check out the code infra dashboard for more information about this PR. |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR removes the slug field from sitemap output, treating it as an internal implementation detail. Previously, slugs were stored in page metadata and returned from the sitemap API. Now, slugs are generated on-demand from page titles when needed (e.g., for anchor links), making the API cleaner and more flexible.
Key Changes
- Type system strengthening: Made
titlerequired inExtractedMetadataandSitemapPageinterfaces, ensuring every page has a title - Slug generation on-demand: Added
titleToSlugutility function to convert titles to URL-friendly slugs when needed - Path-based identification: Changed page lookup logic from slug-based to path-based for more reliable identification
Reviewed changes
Copilot reviewed 18 out of 18 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
packages/docs-infra/src/useSearch/useSearch.tsx |
Added titleToSlug helper and updated search flattening to generate slugs from titles instead of using pre-computed slug field |
packages/docs-infra/src/pipeline/transformMarkdownMetadata/types.ts |
Made title required in ExtractedMetadata, enforcing that all pages must have a title |
packages/docs-infra/src/pipeline/transformMarkdownMetadata/transformMarkdownMetadata.ts |
Added logic to derive title from file path when H1 is missing, with fallback to "Index"; removed slug generation from metadata creation |
packages/docs-infra/src/pipeline/syncPageIndex/syncPageIndex.ts |
Changed page identification from slug-based to path-based for more reliable lookup; added path-based slug extraction for section keys |
packages/docs-infra/src/pipeline/syncPageIndex/metadataToMarkdown.ts |
Removed slug field from PageMetadata; added titleToSlug function to generate anchor links from titles |
packages/docs-infra/src/pipeline/syncPageIndex/syncPageIndex.test.ts |
Updated all test fixtures to remove slug field and adjusted page lookup to use title or path |
packages/docs-infra/src/pipeline/syncPageIndex/metadataToMarkdown.test.ts |
Removed slug assertions and updated test expectations to match new API |
packages/docs-infra/src/pipeline/syncPageIndex/mergeMetadataMarkdown.ts |
Updated alphabetical sorting to use title directly instead of fallback to slug |
packages/docs-infra/src/pipeline/syncPageIndex/mergeMetadataMarkdown.test.ts |
Updated test fixtures and assertions to remove slug references |
packages/docs-infra/src/createSitemap/types.ts |
Made title required and removed slug from SitemapPage interface |
packages/docs-infra/src/pipeline/transformMarkdownMetadata/transformMarkdownMetadata.integration.test.ts |
Removed slug assertions from integration tests |
docs/app/docs-infra/hooks/use-search/page.mdx |
Updated documentation to show how to generate slugs from titles in custom flatten functions |
docs/app/docs-infra/functions/transform-markdown-metadata/page.mdx |
Updated interface documentation and removed "Fallback to slug" note from sorting section |
docs/app/docs-infra/functions/sync-page-index/page.mdx |
Removed slug field from all code examples and interface documentation |
docs/app/docs-infra/functions/load-server-sitemap/page.mdx |
Removed slug from SitemapPage interface documentation |
docs/app/docs-infra/functions/load-server-page-index/page.mdx |
Removed slug from interface documentation and reordered fields |
docs/app/docs-infra/functions/load-precomputed-sitemap/page.mdx |
Removed slug from example JSON output |
docs/app/docs-infra/functions/create-sitemap/page.mdx |
Removed slug from SitemapPage interface documentation |
Janpot
reviewed
Dec 19, 2025
| const { search } = useSearch({ | ||
| sitemap: () => import('./sitemap'), | ||
| flattenPage: (page, sectionData) => { | ||
| const slug = page.title |
Member
There was a problem hiding this comment.
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
- ...?
Janpot
reviewed
Dec 19, 2025
| const foundIndex = pages.findIndex((c) => c.slug === savedSlug); | ||
| if (currentPage?.title) { | ||
| const savedTitle = currentPage.title; | ||
| const foundIndex = pages.findIndex((c) => c.title === savedTitle); |
Member
There was a problem hiding this comment.
What happens when there are two pages with the same title?
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
When storing the sitemap, we need to generate a slug to encode it into markdown.
When we return the sitemap page index, the slug is an internal implementation detail and shouldn't be used because it can be misleading. A page doesn't have a slug; it has a path. If needed, a slug can be generated using the path or the title, depending on the context.
{ - slug: 'checkbox', // this is removed path: './checkbox/page.mdx', title: 'Checkbox', description: 'A checkbox component', }For example, for a given page:
These slugs could be generated:
dialog,components:dialog,popup,components:popup. It's up to the consumer of the sitemap to decide which is desired.This is in response to an issue in base-ui where the slug wasn't generated consistently when writing the sitemap page index.