facebook / facebook/docusaurus
Zero-width space in mdx file path => build fails due to hash mismatch
- Dominant language
- TypeScript
- Stars
- 66.2k
- Forks
- 10k
- Avg merge
- 1d 3h
- Merged PRs (30d)
- 52
Description
### Have you read the Contributing Guidelines on issues?
- [x] I have read the [Contributing Guidelines on issues](https://github.com/facebook/docusaurus/blob/main/CONTRIBUTING.md#issues).
### Prerequisites
- [x] I'm using the latest version of Docusaurus.
- [x] I have tried the `npm run clear` or `yarn clear` command.
- [x] 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)
- [x] 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.
4. Renaming the folder `vulnerability-report` to `foo-bar` resolves the issue.
6. Moving the file back to `docs/contribute/index.mdx` also resolves it. The problem occurs with both `.mdx` and `.md` extensions.
7. 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:
```bash
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`:
```bash
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:
```bash
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`:
```bash
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`:
```bash
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
- [x] 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)
Contributor guide
Assessment
This issue has not been assessed yet.