Links to local directories with dots in filename break docusaurus build

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.
I have read the console error message carefully (if applicable).

Description

Hello,

I have ran into the following issue when generating documentation for some projects:
If one of the md files contains a link to a local directory that has a dot . in its name AND that directory exists, then the docusaurus default mdx plugins will try to parse it using require(), and break the build with the following message:

Module not found: Error: Can't resolve './../directory-with.dot' in '/home/projects/pariqjjolg.github/docs'

Link to repro URL: https://stackblitz.com/edit/github-c3qe69at?file=docs%2Fintro.mdx

Offending line:

[This link breaks the build](../directory-with.dot/)

Probable Cause

The code at transformLinks seems to try to parse the file path and if it has a md-like extension, it calls toAssetRequireNode().

There should probably be added a directory check somewhere here. I am no javascript expert but I can attempt to create a MR if it helps.

Reproducible demo

https://stackblitz.com/edit/github-c3qe69at?file=docs%2Fintro.mdx

Steps to reproduce

From the provided demo just run yarn build.

Or alternatively from a clean repo:

Add this to a parsed md file: [This link breaks the build](../directory-with.dot/)
Create the directory and put a dummy md file in it.
Run yarn build

Expected behavior

The build should pass and link to directory created.

Actual behavior

The following error is produced:

Module not found: Error: Can't resolve './../directory-with.dot' in '/home/projects/pariqjjolg.github/docs'

Your environment

Public source code: https://stackblitz.com/edit/github-c3qe69at?file=docs%2Fintro.mdx
Public site URL: -
Docusaurus version used: 3.10.0
Environment name and version (e.g. Chrome 89, Node.js 16.4): any
Operating system and version (e.g. Ubuntu 20.04.2 LTS): any

Self-service

I'd be willing to fix this bug myself.

fix(mdx-loader): avoid transforming dotted directory links into asset…

Hey! I ran into this as well and took a look at the source. The root cause is in transformLinks/index.ts — path.extname("directory-with.dot/") returns ".dot", so the plugin thinks it's a file asset and tries to require() it through Webpack.

I've put together a fix that adds a quick fs.stat() check after the path resolves. If the target turns out to be a directory instead of a file, it just skips the asset transformation and leaves the link as-is. Added a couple of test cases too.

Will open a PR shortly!

@Dharya-dev

Hello @Dharya-dev, I have also opened a PR for this (#11944), but unfortunately got no response from the devs yet.

@thanasis2028

Hey @thanasis2028, thanks for the heads up! I completely missed that you had already opened a PR for this. Since yours was first and implements the exact same fix, I'll go ahead and close mine (#12037) in favor of yours to keep things tidy for the maintainers. Fingers crossed it gets merged soon!

@Dharya-dev

@Dharya-dev we have also made a work-around plugin that converts links to directory_A/ to directory_A/README.md (if it exists) to avoid the crash. I'm posting it here in case you or somebody else finds it useful:

In docusaurus.config.js:

const remarkFixDottedDirectoryLinks = require('./remarkFixDottedDirectoryLinks');

module.exports = {
  presets: [
    '@docusaurus/preset-classic',
    {
      docs: {
        beforeDefaultRemarkPlugins: [remarkFixDottedDirectoryLinks],
        // other options....
      }
    }
  ]
}

And remarkFixDottedDirectoryLinks.js attached:
remarkFixDottedDirectoryLinks.js

Navigation Menu

Repository navigation

Links to local directories with dots in filename break docusaurus build #11940

Have you read the Contributing Guidelines on issues?

Prerequisites

Description

Probable Cause

Reproducible demo

Steps to reproduce

Expected behavior

Actual behavior

Your environment

Self-service

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Links to local directories with dots in filename break docusaurus build #11940

Description

Have you read the Contributing Guidelines on issues?

Prerequisites

Description

Probable Cause

Reproducible demo

Steps to reproduce

Expected behavior

Actual behavior

Your environment

Self-service

Activity

Dharya-dev commented on May 18, 2026

thanasis2028 commented on May 18, 2026

Dharya-dev commented on May 18, 2026

thanasis2028 commented on May 19, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions