[docs] Fix pathname collision in LLMs docs generator #47209
Conversation
When multiple markdown files exist in the same directory, findPagesMarkdown() strips filenames causing pathname collisions. This resulted in the wrong file content being used (e.g., upgrade-to-v7.md incorrectly contained content from upgrade-to-native-color.md). Fix by matching files based on filename basename + parent path verification instead of relying solely on the stripped pathname. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
siriwatknp
added
the
scope: docs-infra
Netlify deploy previewhttps://deploy-preview-47209--material-ui.netlify.app/ Bundle size report
|
There was a problem hiding this comment.
Pull Request Overview
This PR modifies the file matching logic in the findNonComponentMarkdownFiles function to fix pathname collision issues when multiple markdown files exist in the same directory.
Key Changes:
- Replaced simple pathname equality check with a more sophisticated matching algorithm that compares file basenames and verifies parent directory paths
- Added logic to extract the last segment from pathnames and match against actual file basenames
- Introduced parent path verification to ensure files are located in the correct directory structure
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| // exist in the same directory (e.g., upgrade-to-v7.md and upgrade-to-native-color.md) | ||
| const lastSegment = pathname.split('/').filter(Boolean).pop(); | ||
| const page = allMarkdownFiles.find((p) => { | ||
| const fileBasename = path.basename(p.filename, '.md'); |
There was a problem hiding this comment.
The path.basename() call only strips the .md extension, but findPagesMarkdown() also returns files with .mdx extensions. For .mdx files, the basename will incorrectly include the .mdx suffix, causing the comparison to fail. Use path.basename(p.filename).replace(/\.mdx?$/, '') to handle both .md and .mdx files.
| const fileBasename = path.basename(p.filename, '.md'); | |
| const fileBasename = path.basename(p.filename).replace(/\.mdx?$/, ''); |
| const page = allMarkdownFiles.find((p) => { | ||
| const fileBasename = path.basename(p.filename, '.md'); | ||
| const parentPath = parsedPathname.replace(/\/[^/]+$/, ''); | ||
| return fileBasename === lastSegment && p.filename.includes(parentPath); |
There was a problem hiding this comment.
The p.filename.includes(parentPath) check is too loose and could match files in subdirectories. For example, when looking for /material-ui/migration/upgrade-to-v7 (which should match a file at docs/data/material/migration/upgrade-to-v7.md), this would incorrectly also match docs/data/material/migration/v7/upgrade-to-v7.md because that filename also contains /material/migration. Consider using p.pathname === parentPath instead, which would provide an exact directory match and avoid false positives from files in subdirectories.
| return fileBasename === lastSegment && p.filename.includes(parentPath); | |
| return fileBasename === lastSegment && path.dirname(p.filename) === parentPath; |
2 participants
Root Cause
Before: https://mui.com/material-ui/migration/upgrade-to-v7.md (show native color content which is wrong)
The
findNonComponentMarkdownFiles()function usesfindPagesMarkdown()which strips the filename from the path to create a "pathname". When multiple markdown files exist in the same directory, they produce identical pathnames:The
find()method then returns the first alphabetically ordered file (upgrade-to-native-color.md), causingupgrade-to-v7.mdto be generated with the wrong content.Solution
Updated the file matching logic to use:
upgrade-to-v7)This prevents collisions while maintaining compatibility with the existing file structure.
Testing
Verified all 13 migration files generate with correct content:
upgrade-to-v7.md→ "Upgrade to v7" contentupgrade-to-native-color.md→ "Upgrade to native color" content