Windows Path Separator Issue

[dingshaohua-com]

Bug Report: Windows Path Separator Issue

---

Title: Navigation warnings and missing sidebar titles on Windows due to path separator mismatch

---

Description

When running mint dev on Windows, the CLI reports warnings that files referenced in docs.json do not exist, even though the files are present. Additionally, the sidebar displays file paths instead of the title from MDX frontmatter. This issue does not occur on macOS or Linux.

Environment

• OS: Windows 10/11
• Node.js: v20.x
• Mintlify CLI: 4.0.830+ (via mint package)
• Package Manager: pnpm / npm

Steps to Reproduce

1. Create a Mintlify project on Windows with the following structure:

   docs/
   ├── docs.json
   └── contents/
       └── python/
           └── index.mdx
   

2. Configure docs.json with navigation:

   {
     "navigation": {
       "tabs": [
         {
           "tab": "Python",
           "groups": [
             {
               "group": "Getting Started",
               "pages": ["contents/python/index"]
             }
           ]
         }
       ]
     }
   }

3. Run mint dev on Windows.

Expected Behavior

• No warnings about missing files
• Sidebar displays the title from MDX frontmatter

Actual Behavior

• Warning: "contents/python/index" is referenced in the docs.json navigation but the file does not exist.
• Sidebar shows file path instead of frontmatter title
• Pages still load correctly (the issue is only with path matching)

Root Cause Analysis

The issue is in @mintlify/prebuild package, specifically in dist/fs/index.js.

The getFileList function uses path.relative() which returns backslashes (\) on Windows:

// Line 50-51 in dist/fs/index.js
else {
    yield `/${relativePath}`;  // relativePath = "contents\\python\\index.mdx" on Windows
}

This produces paths like /contents\python\index.mdx, which don't match the forward-slash paths in docs.json (contents/python/index).

Suggested Fix

Normalize path separators to forward slashes:

else {
    yield `/${relativePath.replace(/\\/g, '/')}`;
}

The same fix should be applied to:

• getFileListSync (line 14)
• getFileListWithDirectories (lines 27, 34)

Workaround

Manually patch node_modules/@mintlify/prebuild/dist/fs/index.js with the fix above, or use WSL on Windows.

---

[dingshaohua-com]

@mintlify__prebuild.patch

How to Use This Patch

1. Create a patches/ folder in your project root
2. Put @mintlify__prebuild.patch file inside
3. Add the following to your package.json:

{
  "pnpm": {
    "patchedDependencies": {
      "@mintlify/prebuild": "patches/@mintlify__prebuild.patch"
    }
  }
}

4. Run pnpm install

Done! The patch will be applied automatically.