Markdown-style links to notes are never resolved: full reload, then a dead end

[BattermanZ]

Found while routing in-body note links through the router. That change fixed the full page reload for wikilinks, which are the only note links Hatchdoor resolves. A note link written the plain-Markdown way is a different problem: it has never worked, and it does not merely reload, it lands nowhere.

What happens

A link like [Beacon Launch](Beacon%20Launch.md) renders as a link, is clickable, and goes to a dead end. The href is left exactly as the author wrote it, so the browser resolves it against the current note's URL.

Measured in Chromium against just dev-start, from a note in 00-inbox linking to 20-projects/Beacon Launch.md:

written in the note	href in the page	where the click lands	what the reader sees
[[Beacon Launch]]	/v/<id>/n/beacon-launch	the note	works, router navigation
[x](Beacon%20Launch.md)	Beacon%20Launch.md	/v/<id>/n/Beacon%20Launch.md	full page reload, then "Note not found: Beacon Launch.md"
[x](20-projects/Beacon%20Launch.md)	20-projects/Beacon%20Launch.md	/v/<id>/n/20-projects/Beacon%20Launch.md	full page reload, then a blank pane: no route matches, so nothing renders and no error is shown
[x](../20-projects/Beacon%20Launch.md)	../20-projects/Beacon%20Launch.md	/v/<id>/20-projects/Beacon%20Launch.md	same blank pane

The blank-pane cases are the worse ones. The sidebar is there, the main pane is empty, and nothing says why.

These links are also invisible to backlinks, the Links panel, the graph and statistics, so a vault using them looks unlinked even where it is densely cross-referenced.

Note that a target with a raw space, [x](Beacon Launch.md), is not a link at all under CommonMark and renders as literal text. Only the percent-encoded form reaches this path, which is the form Obsidian writes.

Cause

Two places understand [[ ]] and nothing else.

extract_wikilink_targets in src/vault/links.rs:82 scans each non-code line for [[ and collects what follows. It feeds outgoing links and backlinks, and through them the Links panel, the graph and the link statistics. A Markdown link contributes nothing to any of them.

rewriteWikilinks in frontend/src/components/note-page/wikilinks.ts:50 matches /(!?)\[\[([^\]\r\n]+)\]\]/g and rewrites a resolved hit into /v/<vault>/n/<slug>. A Markdown target is never sent to resolve-batch and never rewritten.

By the time the href reaches the markdown renderer's a component in frontend/src/components/note-page/renderers.tsx, it is a relative filename. It is not a sentinel, not external, not a PDF and not a note route, so it falls to the plain anchor branch and the browser takes it from there.

Who hits this

Obsidian's Files and links settings carry a Use [[Wikilinks]] toggle. With it switched off, Obsidian writes every new link in the Markdown form with a percent-encoded path. A vault authored that way has no working note links in Hatchdoor at all, and no backlinks either, while looking completely normal in Obsidian.

Suggested direction

The resolver already knows how to answer this. normalize_link_target in src/vault/paths.rs:29 strips a .md suffix and normalises separators, and resolve_target_slug matches a target by path-title or by basename. A Markdown target is exactly the shape those two already accept. The missing step is recognising it as a note reference in the first place.

Two decisions to take before writing anything:

How far the fix goes. Rewriting the href in wikilinks.ts makes the links navigate and is frontend-only. Teaching extract_wikilink_targets about the Markdown form as well makes them count as links, which is more correct but changes backlinks, the graph and the statistics for every existing vault, and needs a decision about whether that shift is wanted.

What an unresolved or non-note target does. A wikilink that resolves to nothing renders as a broken-link span rather than a link. A Markdown target that names no note should presumably do the same, but that means deciding what "names no note" is for a target that could equally be an attachment. Related: the .pdf branch already rewrites a relative PDF target to the asset endpoint, while other attachment extensions, .mp4 among them, fall through to the same bare anchor and the same dead URL. Worth settling both in one pass, since it is one classifier.

Scope

Navigation only: frontend/src/components/note-page/wikilinks.ts, frontend/src/components/note-page/renderers.tsx, and their tests.

Including link records: src/vault/links.rs and its resolver, plus whatever the note-links contract change pulls in. That path needs the interface-change checklist and probably an ADR, since backlinks are a supported contract and existing vaults would see their link counts move.

Priority note

Low, with a caveat. Nothing regressed, this has never worked, and a vault authored with wikilinks throughout never produces the shape. But it is silent: the links look right, the blank-pane variant reports nothing, and someone arriving from an Obsidian vault with wikilinks turned off would find every link in their vault broken with no message explaining it. That makes it worth a decision even if the fix waits.

[BattermanZ]

This was generated by AI during triage.

Triage Notes

Recategorised from bug to enhancement, and left in triage rather than moved on. The reasoning, the corrections to the original report, and the four decisions settled during triage are below so none of it has to be re-derived.

The bug half has been split out into #302. The blank pane is not a link problem: Hatchdoor has no answer for any address it does not recognise, and Markdown-style links were one of several ways to reach it. That issue is specified and ready. What remains here is adding support for a link form Hatchdoor has never supported, which is an enhancement.

What was verified

The report is accurate. Every row of its table follows from the code, and the cause it names is the right one.

The rewriter that turns links into router navigation matches only the [[ ]] form, so a Markdown-form target reaches the renderer untouched. The renderer then asks five questions of an href: is it broken, archived, external, a PDF, a note address. A bare relative filename answers no to all five and becomes an ordinary browser link, at which point the browser resolves it against the current note's URL.

Corrections to the report

The .mp4 case is not part of this classifier. Hatchdoor's list of servable file types is images plus PDF, nothing else. A .mp4 in a vault is never indexed as an attachment, so recognising the link form would not make it work; it would resolve to nothing. Whether Hatchdoor should serve more file types is a separate attachment question and does not belong to this issue.

The blank pane is worse than reported, and worse in production than in development. The measurement in the report was taken against the Vite dev server, which serves the app for any address. The production server registers the app's index for five specific paths and answers everything else from the static file directory. Measured against a running instance: the five known routes answer 200, every other address answers 404. So a first-time visitor gets a bare browser 404 rather than a blank pane, and a returning visitor gets the blank pane because the service worker's navigation fallback serves them the cached index. Same address, two different answers. See #302.

What the report missed

A fourth surface. Beyond navigation, link records and the resolver, renaming or moving a note rewrites every link in the vault that pointed at it, and deleting one removes those links. That rewriting understands [[ ]] and nothing else. Today that is harmless because Markdown links do not work anyway. The moment they do, a rename silently rots them, which trades one silent failure for a slower one.

The two resolvers disagree about what a path means. An attachment target is resolved by a four-step ladder: leading / means vault root, then relative to the note's own folder, then as written from the vault root, then by filename anywhere with the nearest match winning. A note target is resolved by a shorter and different rule: the whole target as a path from the vault root, then the last path segment as a title, then as a slug. It has no idea which folder the link was written in. That difference has never mattered because a wikilink target is a title rather than a path. A Markdown target is a path, so it starts mattering here.

Decisions settled during triage

1. Only a target ending .md is treated as a note reference. Everything else keeps its current behaviour. This removes the ambiguity the report flagged: notes and attachments are disjoint lists in the index and a .md file is never an attachment, so a .md naming no note is unambiguously a broken note link with nothing to guess at. The cost accepted is that a link written without the extension stays dead.

2. A .md target is resolved by the same four-step ladder attachments already use, note's own folder included, rather than by the existing note rule. Obsidian writes these targets relative to the note, so ../ forms will be common. Feeding them to the current note rule appears to work, but only through its last-segment fallback, which silently picks the wrong note when two notes share a title. A link that looks like it worked and went somewhere else is a worse failure than the dead end this issue reports.

3. Rename, move and delete retarget the Markdown form alongside wikilinks, with one exception: on delete the link text is kept and only the link removed. Removing a wikilink outright is fine because the whole thing was the note's name, but a Markdown link's visible text is the author's own prose and deleting a note must not swallow words mid-paragraph.

4. Scope stays navigation plus file rewriting. Link records are explicitly out: backlinks, the Links panel, the graph and statistics keep counting only wikilinks. Changing that moves numbers people already see for every existing vault, and remains a separate decision needing the interface-change checklist and an ADR.

Still open

• What an unresolved .md target renders as. Decision 1 removes the ambiguity, so matching the broken-link treatment wikilinks already get is the likely answer, but it has not been taken.
• Whether an anchor on a Markdown target carries through to the heading, the way it does for a wikilink.
• Percent-decoding. %20 has to be decoded before matching, and a filename containing a literal % needs a rule.

Why this is not being built now

Obsidian ships with wikilinks on. The Markdown form only appears if someone deliberately turns the toggle off, which people do for portability with tools that do not understand [[ ]]. That is a real group, and arguably the group most likely to go looking for a second tool, but it is small.

No vault available to the project contains a single Markdown-style note link: not the demo vaults, the starter vault, the documentation vault, or a working vault. No user has reported it.

And there is no cheap version. The small fix is decision 2's rejected alternative, which resolves to the wrong note on a title collision. The choice is a proper fix, meaning a new resolution path plus changes to the code that rewrites note files on rename, or nothing. That is a lot of new machinery in the write path for a link form that has never appeared in front of a user.

The design above is done, so if a real Obsidian vault authored this way ever turns up, this goes straight to an agent rather than starting over.