Skip to content

broken-links incorrectly treats Chinese filename links as broken in Chinese docs #6895

Description

@onewesong

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
    • 营收与毛利账本.md
    • etc.

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

  1. Create two markdown files with Chinese names in same folder:
    • 营收与毛利账本设计.md
    • Datadog营收看板方案.md
  2. In Datadog营收看板方案.md add:
    - [营收与毛利账本设计](./营收与毛利账本设计.md)
  3. Run mint broken-links.

Observed: this valid link is reported as broken in multiple cases.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions