fix: resolve slug conflict when index/README and dirname file coexist

[Vedthakar]

Pre-flight checklist

• I have read the Contributing Guidelines on pull requests.
• If this is a code change: I have written unit tests and/or added dogfooding pages to fully verify the new behavior.
• If this is a new API or substantial change: the PR has an accompanying issue (closes Inaccesability of index when there also a file matching the directory name #8555) and the maintainers have approved on my working plan.

Motivation

Closes #8555.

This PR fixes a slug conflict in the docs plugin when multiple files in the same directory are recognized as category indexes and would otherwise resolve to the same permalink.

The concrete bug reported in #8555 is:

• docs/demo/index.md
• docs/demo/demo.mdx

Both currently map to /docs/demo/, which makes one of them inaccessible. The same conflict can also happen with README.md and a file matching the directory name.

This change applies a priority order for category-index-style docs:

• index
• README
• <dirname>

If a lower-priority file loses the conflict, it is reassigned a regular non-category-index slug so that both docs remain accessible. For example, when index.md and demo.mdx coexist, index.md keeps /demo/ and demo.mdx becomes /demo/demo.

For conflicts that still cannot be resolved automatically, the loader now throws a clear duplicate permalink error and points users toward using explicit slug front matter.

This keeps the fix narrowly scoped to permalink resolution, uses existing docs-plugin/category-index utilities instead of hardcoded filename logic, and preserves current behavior everywhere else.

Test Plan

I added focused tests in loadVersion.test.ts with a dedicated fixture site covering the new conflict resolution behavior.

Verified locally:

• targeted slug-conflict tests pass
• full docusaurus-plugin-content-docs test suite passes
• TypeScript check for the package passes

Commands used:

yarn jest packages/docusaurus-plugin-content-docs/src/versions/__tests__/loadVersion.test.ts --testNamePattern="slug conflict"
yarn jest packages/docusaurus-plugin-content-docs
yarn tsc -p packages/docusaurus-plugin-content-docs/tsconfig.json --noEmit

Closes #8555

Also related to:

• Inaccesability of index when there also a file matching the directory name kkipngenokoech/docusaurus#2

[netlify]

✅ [V2]

Built without sensitive environment variables

Name	Link
🔨 Latest commit	2386b6e
🔍 Latest deploy log	https://app.netlify.com/projects/docusaurus-2/deploys/69d4f48c147b6e000822b4d9
😎 Deploy Preview	https://deploy-preview-11910--docusaurus-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.