Free tool · works now

Broken Wikilink Finder

Audit Markdown wikilinks across vaults to find missing note targets, case mismatches, and typos.

Runs 100% in your browser. Audit Markdown wikilinks across your vault, isolate aliases, find missing note dead ends, detect cross-platform casing mismatches, and export placeholder note lists.

11Wikilinks
6Resolved
2Missing notes
1Case mismatch
1Ambiguous
1Typos
Source Markdown notes830 chars
Vault file inventory11 files
Wikilink Resolution Audit11 analyzed
LineRaw WikilinkTarget NoteAliasStatusMatched File / Suggested Action
6[[Architecture Overview]]Architecture Overview—ResolvedResolved to "Architecture Overview.md".
7[[Storage Engine Architecture|Storage Engine]]Storage Engine ArchitectureStorage EngineResolvedResolved to "Storage Engine Architecture.md".
8[[system requirements]]system requirements—Case mismatchCase mismatch: Target "system requirements" vs vault file "System Requirements.md".
Suggested: [[System Requirements]]
9[[Distributed Consensus]]Distributed Consensus—Missing noteTarget note "Distributed Consensus" does not exist in the provided vault inventory.
10[[Memmory Hierarchy]]Memmory Hierarchy—TypoPossible typo (distance: 1). Closest existing note is "Memory Hierarchy.md".
Suggested: [[Memory Hierarchy]]
11![[system-diagram.png]]system-diagram.png—ResolvedResolved to "system-diagram.png".
12[[Storage Engine Architecture#Configuration|WAL Settings]]Storage Engine ArchitectureWAL SettingsResolvedResolved to "Storage Engine Architecture.md".
13[[Module Readme]]Module Readme—AmbiguousAmbiguous target: 2 files share filename "Module Readme" (services/auth/Module Readme.md, services/billing/Module Readme.md).
14[[Quantum Cryptography RFC]]Quantum Cryptography RFC—Missing noteTarget note "Quantum Cryptography RFC" does not exist in the provided vault inventory.
22[[Sprint 42 Backlog]]Sprint 42 Backlog—ResolvedResolved to "Sprint 42 Backlog.md".
23[[Team/Sarah Connor|Sarah Connor]]Team/Sarah ConnorSarah ConnorResolvedResolved to "Team/Sarah Connor.md".
Missing Notes Placeholder List2 notes
Formula-Guarded CSV ExportSpreadsheet ready
"Line","Raw Link","Target","Alias","Anchor","Status","Matched File","Explanation"
"Line 6","[[Architecture Overview]]","Architecture Overview","None","None","resolved","Architecture Overview.md","Resolved to ""Architecture Overview.md""."
"Line 7","[[Storage Engine Architecture|Storage Engine]]","Storage Engine Architecture","Storage Engine","None","resolved","Storage Engine Architecture.md","Resolved to ""Storage Engine Architecture.md""."
"Line 8","[[system requirements]]","system requirements","None","None","case-mismatch","System Requirements.md","Case mismatch: Target ""system requirements"" vs vault file ""System Requirements.md"". (Fix: [[System Requirements]])"
"Line 9","[[Distributed Consensus]]","Distributed Consensus","None","None","broken","None","Target note ""Distributed Consensus"" does not exist in the provided vault inventory."
"Line 10","[[Memmory Hierarchy]]","Memmory Hierarchy","None","None","near-match","Memory Hierarchy.md","Possible typo (distance: 1). Closest existing note is ""Memory Hierarchy.md"". (Fix: [[Memory Hierarchy]])"
"Line 11","![[system-diagram.png]]","system-diagram.png","None","None","resolved","system-diagram.png","Resolved to ""system-diagram.png""."
"Line 12","[[Storage Engine Architecture#Configuration|WAL Settings]]","Storage Engine Architecture","WAL Settings","#Configuration","resolved","Storage Engine Architecture.md","Resolved to ""Storage Engine Architecture.md""."
"Line 13","[[Module Readme]]","Module Readme","None","None","ambiguous","services/auth/Module Readme.md","Ambiguous target: 2 files share filename ""Module Readme"" (services/auth/Module Readme.md, services/billing/Module Readme.md)."
"Line 14","[[Quantum Cryptography RFC]]","Quantum Cryptography RFC","None","None","broken","None","Target note ""Quantum Cryptography RFC"" does not exist in the provided vault inventory."
"Line 22","[[Sprint 42 Backlog]]","Sprint 42 Backlog","None","None","resolved","Sprint 42 Backlog.md","Resolved to ""Sprint 42 Backlog.md""."
"Line 23","[[Team/Sarah Connor|Sarah Connor]]","Team/Sarah Connor","Sarah Connor","None","resolved","Team/Sarah Connor.md","Resolved to ""Team/Sarah Connor.md""."

The anatomy of broken wikilinks in personal knowledge vaults

Bidirectional linking using double-bracket wikilinks ([[Note Name]]) is the foundation of network-based thought in Obsidian, Roam Research, Logseq, and Foam. As knowledge graphs expand across hundreds or thousands of files, dead references inevitably accumulate. Notes get renamed without updating incoming backlinks, reference links are drafted for future thoughts that remain unwritten, and typos silently fragment knowledge networks.

Dangling wikilinks create graph holes where intended connections fail to bridge related concepts. Without automated validation against your actual file system inventory, knowledge workers operate under the false assumption that notes are properly cross-referenced.

Handling aliases, heading anchors, and block references

Naive regular expressions often fail when evaluating modern Markdown wikilinks because authors frequently enrich references with modifiers:

  • Piped Aliases: Syntax like [[Storage Architecture|Storage Subsystem]] uses the pipe character to display reader-friendly prose while pointing to a distinct filename. Resolving the alias rather than the destination causes valid files to be erroneously flagged as absent.
  • Heading Deep Links: References such as [[Project Roadmap#Milestone 3]] point to specific sections within a note. The host note must be evaluated independently of the section anchor.
  • Block References: Links pointing to individual paragraph blocks ([[Meeting Minutes#^89f2a]]) require isolating the base document name.

The cross-platform casing hazard: APFS, NTFS, and Linux

One of the most insidious sources of vault corruption is file casing. On macOS and Windows, the underlying filesystems (APFS and NTFS) are case-preserving but case-insensitive. A link authored as [[system requirements]] resolves seamlessly to System Requirements.md on a desktop Mac.

However, when that same vault is synchronized to Linux servers, exported to GitHub repositories, or compiled into static websites, case sensitivity takes effect. The case-mismatched link fails instantly, presenting readers with dead 404 links. The Broken Wikilink Finder isolates case mismatches before they cause deployment failures.

Ambiguous paths and shortest-path conventions

In modular vaults with multiple subfolders (such as projects/auth/Readme.md and projects/billing/Readme.md), authoring a link as [[Readme]] creates an ambiguous target. Depending on the resolution strategy:

  1. Shortest Path Mode: Obsidian attempts to match any file sharing the name, choosing the nearest ancestor or the first alphabetical match.
  2. Strict Path Mode: Links require explicit relative or absolute folder paths to avoid accidental routing to the wrong project.

Our analyzer audits both conventions, warning authors whenever multiple identical note names exist in their file tree.

Related note and document utilities

Explore companion local browser utilities for maintaining resilient Markdown collections:

Questions

How does the Broken Wikilink Finder separate piped aliases from note targets?

In Obsidian and Foambound vaults, syntax such as `[[Storage Engine Architecture|Storage]]` displays custom label text while pointing to an underlying note file. The parser separates the destination note from the pipe delimiter, ensuring that file resolution matches the actual note filename rather than the alias.

Why do case mismatches cause problems across different devices and operating systems?

macOS (APFS) and Windows (NTFS) are default case-insensitive filesystems, meaning `[[system requirements]]` successfully opens `System Requirements.md`. However, Linux servers, GitHub Pages, mobile sync engines, and web publishing tools treat casing as distinct. Case-inconsistent links will silently break when vaults are shared or synced.

What is the difference between shortest-path and strict-path wikilink resolution?

Under Obsidian’s default "shortest path" convention, writing `[[Overview]]` automatically resolves to `projects/alpha/Overview.md` if no other file shares that name. Under strict-path resolution, links must explicitly state directory structures (e.g. `[[projects/alpha/Overview]]`). The finder lets you audit your vault under both modes.

How does the tool handle heading anchors and block references inside wikilinks?

The engine strips `#heading` anchors and `^block-id` suffixes prior to testing file existence, verifying that the host note actually exists in your inventory while retaining the anchor string in audit exports.

Does this tool upload or store my vault notes or folder structures?

No. All wikilink parsing, inventory indexing, and typo distance calculations execute entirely inside your local browser tab. No notes, file lists, or metadata are ever transmitted across networks.

Want unbroken knowledge graphs across your local notes?

Complete Obsidian vault compatibility, plain text Markdown on disk, and private on-device notes in Oyma.

tools broken wikilink finder downloadDownload for Mac

No account needed. Intel Mac build