[BUG] Build fails when creating `docs/contribute/vulnerability-report/index.mdx`, but creating the file in another directory does not cause the error (very weird but reproducible)

[coder-xiaomo]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Prerequisites

• I'm using the latest version of Docusaurus.
• I have tried the npm run clear or yarn clear command.
• I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• I have tried creating a repro with https://new.docusaurus.io.
  (because of the network problem, I can't work with CodeSandbox and StackBlitz, but it can reproduce in the clean new project)
• I have read the console error message carefully (if applicable).

Description

1. In a fresh Docusaurus project on Windows using npm, creating docs/contribute/index.mdx works fine.
2. However, moving that same file into docs/contribute/vulnerability-report/index.mdx causes the build to fail.
   
3. Renaming the folder vulnerability-report to foo-bar resolves the issue.
   
4. Moving the file back to docs/contribute/index.mdx also resolves it. The problem occurs with both .mdx and .md extensions.
5. Moving the file back to docs/contribute/vulnerability-report/index.mdx again, the build fail again.

Reproducible demo

https://github.com/coder-xiaomo/docusaurus-bug-minimal-repro/commits/main/

Steps to reproduce

1. Create a new Docusaurus project using npm on Windows:

   npx create-docusaurus@latest my-website classic --typescript
   cd my-website
   npm install

2. Create a file docs/contribute/index.mdx with any content (e.g., # Test).

3. Run npm start – the site builds successfully and the doc displays at /docs/contribute.

4. Stop the server. Move the file into a new subdirectory vulnerability-report:

   mkdir docs\contribute\vulnerability-report
   move docs\contribute\index.mdx docs\contribute\vulnerability-report\index.mdx

   Then run npm start – build fails (error details below).

5. Stop the server. Clean the cache and dependencies:

   rmdir /s /q .docusaurus
   rmdir /s /q node_modules
   npm install

   After reinstallation, run npm start again – the error still occurs.

6. Stop the server. Rename the vulnerability-report folder to foo-bar:

   move docs\contribute\vulnerability-report docs\contribute\foo-bar

   Run npm start – the build now works correctly.

7. Stop the server. Move the file back to docs/contribute/index.mdx:

   move docs\contribute\foo-bar\index.mdx docs\contribute\index.mdx

   Run npm start – the build works correctly again.

8. (Optional) Repeat the same steps using a .md file instead of .mdx – the problem is reproducible exactly the same way.

Expected behavior

The build should succeed, and the doc should be accessible at /docs/contribute/vulnerability-report without any hash mismatch. Deleting .docusaurus and node_modules should not be necessary for a correct build.

Actual behavior

When the file is located at docs/contribute/vulnerability-report/index.mdx, the build fails with a module resolution error:

× Cannot find module '@site/.docusaurus/docusaurus-plugin-content-docs/default/site-docs-contribute-vulnerability-report-index-mdx-e58.json' for matched aliased key '@site'

Meanwhile, inside .docusaurus/docusaurus-plugin-content-docs/default/, the actual generated file is:

site-docs-contribute-vulnerability-report-index-mdx-b66.json

Notice the hash mismatch: looking for -e58 but the file exists with -b66.

Your environment

• Public source code: https://github.com/coder-xiaomo/docusaurus-bug-minimal-repro/commits/main/
• Public site URL:
• Docusaurus version used: latest (3.10.1)
• Environment name and version: Microsoft Edge 147.0.3912.98; Node.js v24.14.1
• Operating system and version: Windows 11

Self-service

• I'd be willing to fix this bug myself. (but I am not sure where the root cause is. If the root cause was found, maybe I can create an pull request to fix it)