Environment
- OS: Linux
- mint version: 4.2.742
- Node: v24.18.0
- Repo root: operating-analysis (Markdown docs)
Current behavior
mint broken-links reports many false positives when markdown files/anchors use non-ASCII filenames in links, especially Chinese file names.
Why this seems wrong
In our docs, these are real files and valid links, but mint broken-links still marks them broken:
revenue_margin/Datadog营收看板变更记录.md
./营收与毛利账本设计.md
../doris/revenue_ledger/README.md (as another example)
shared_docs/revenue_margin_guides/历史营收查询.md
Root cause observed from source code
I traced MdxPath.toString() behavior in @mintlify/link-rot:
- Internal markdown link targets are normalized via
new URL(mintlify:...).
- For Chinese paths,
toString() becomes URL-encoded (e.g. %E8%90...), e.g. 营收与毛利账本设计.md -> %E8%90%A5%E6%94%B6...md.
But page discovery from getLinkPaths() uses raw filesystem paths.
So the lookup key is encoded but target entries are not.
Result: valid links are treated as broken.
Expected behavior
Chinese path links should be resolved same as markdown paths with UTF-8 filenames, or link checker should normalize in a way that treats raw and encoded paths as equivalent.
Repro
- Create two markdown files with Chinese names in same folder:
营收与毛利账本设计.md
Datadog营收看板方案.md
- In
Datadog营收看板方案.md add:
- [营收与毛利账本设计](./营收与毛利账本设计.md)
- Run
mint broken-links.
Observed: this valid link is reported as broken in multiple cases.
Environment
Current behavior
mint broken-linksreports many false positives when markdown files/anchors use non-ASCII filenames in links, especially Chinese file names.Why this seems wrong
In our docs, these are real files and valid links, but
mint broken-linksstill marks them broken:revenue_margin/Datadog营收看板变更记录.md./营收与毛利账本设计.md../doris/revenue_ledger/README.md(as another example)shared_docs/revenue_margin_guides/历史营收查询.md营收与毛利账本.mdRoot cause observed from source code
I traced
MdxPath.toString()behavior in@mintlify/link-rot:new URL(mintlify:...).toString()becomes URL-encoded (e.g.%E8%90...), e.g.营收与毛利账本设计.md->%E8%90%A5%E6%94%B6...md.But page discovery from
getLinkPaths()uses raw filesystem paths.So the lookup key is encoded but target entries are not.
Result: valid links are treated as broken.
Expected behavior
Chinese path links should be resolved same as markdown paths with UTF-8 filenames, or link checker should normalize in a way that treats raw and encoded paths as equivalent.
Repro
营收与毛利账本设计.mdDatadog营收看板方案.mdDatadog营收看板方案.mdadd:mint broken-links.Observed: this valid link is reported as broken in multiple cases.