Markdown preview: Obsidian-style [[wikilinks]]

Plan of record · shipped in #1212 · builds directly on the relative-link work (the bug note “repo-relative links open the target file”, shipped in PR #1190). Verdict: ~half a day, low risk.

How wikilinks render and resolve

A wikilink is not a regular link with different syntax — it should look like a different kind of reference. Regular Markdown links keep today’s link-blue underline; a wikilink gets its own violet, bracketed treatment that reads as “internal note reference,” uniformly, whether or not it resolves.

Code tab · rendered Markdown preview

[the limitations doc](LIMITATIONS.md)

regular markdown link

the limitations doc

underlined link-blue — unchanged

[[Architecture]]

wikilink

⟦Architecture⟧

violet, bracketed — reads as an internal note reference

[[Architecture|the arch doc]]

wikilink · aliased

⟦the arch doc⟧

alias is the visible text; same style

Resolution is lazy — on click, never at render time. The preview doesn’t pre-check every [[…]] against the file list to grey out dead ones; it renders them all alike and resolves the one you actually click. That keeps the renderer a pure presenter (no file-list dependency threaded into it) and matches how the relative-link path already works.

open the ⟦Note⟧ doc

a/Note.md

b/Note.md

Click on an ambiguous [[Note]] (two Note.md) → a menu anchored to the link lists the matching files; pick one to open it.

The hard part — the vault index — already ships

The obvious worry with Obsidian wikilinks is resolution: [[Architecture]] is pathless — it finds Architecture.md by basename, scanning the whole repo, with no directory hint. That sounds like it needs a new file index.

It doesn’t. fsListAll already streams git ls-files --cached --others --exclude-standard into the client (integrations/git/src/browse.ts), materialised as treePaths() in CodeTab.tsx — a live, gitignore-respecting, NFC-normalised list of every repo path, already the back-end of the “open this file” front door.

Where it lives — by feature, not by topic

The wikilink resolver lives in @kolu/solid-markdown next to its parser: a wikilink is a Markdown construct, and the resolution rules (.md implied, alias/heading, ambiguity-surfacing) are defined by the wikilink grammar — nothing outside Markdown resolves one. It’s a pure, node-pure, host-called export (like url-policy’s safeHref), so it does not couple the renderer to the file list. It is not in @kolu/solid-browser: that package’s concern is browsing (location, history, link interception, GitHub-relative path math). Its resolveLinkHref — directory-relative [](…) resolution with no file list — is a different concept that genuinely is a browsing concern and stays there. Two link resolvers, two packages, split by feature rather than bundled under the word “link.”

The pieces

The relative-link work (PR #1190) cut most of the seam: a tagged anchor, a host callback, and the openInCodeTab front door. Wikilinks add a parser in front of it and a resolver + menu behind it.

The wikilink feature — parser, resolver, and host callback — lives wholly in @kolu/solid-markdown; the client dispatcher only wires it to the menu and the existing open-in-Code-tab front door. The marked extension mints a distinct data-md-wikilink anchor; resolveWikilink does the pathless, .md-implied vault match and surfaces candidates instead of collapsing to null. The sanitizer gains one allowlisted marker (and a guard that strips it from any escaping href); the front door and the file list are untouched.

Why a separate onNavigateWikilink callback rather than reusing onNavigateRelative: the two differ on two axes — the resolution model (pathless vault vs. the doc’s directory) and the need for the clicked element, so the host can anchor the disambiguation menu to it. The menu itself is no new machinery — it reuses OptionMenu + useAnchoredPopover, the same anchored option-list the Dock and minimap pickers use. repoPaths is threaded from CodeTab (which owns treePaths()) down to the dispatcher, since the front door resolves internally and never exposes the candidate set the menu needs.

Scope

![[embeds]] (transclusion) — no. Inlining a note’s body or an image is not a link; it’s a render-time content splice with its own recursion, cycle, and sizing concerns. ![[…]] is left as inert literal text, never expanded.
Heading scroll-after-open — out of scope. A [[Note#Heading]] opens the file; scrolling to #Heading inside it is not handled here — the same gap the relative-link fix left for []() fragments.

Why this stays simple

One concept, isolated volatility

Wikilinks don’t fork the renderer. They’re a second parser (the [[…]] syntax) feeding a second resolution model (pathless basename) into the same open-in-Code-tab front door. The genuinely new volatility — “how does this token’s target become a path, and what happens when it’s ambiguous?” — is isolated to one marked extension, one resolver, and one dispatcher branch. The sanitizer’s only contact is mechanical, not conceptual: it allowlists the data-md-wikilink marker so the parser’s tag survives, and guards it (the marker is honored only for a safe, scheme-less, non-fragment href; an escaping one — external URL, unsafe scheme, or #frag — is stripped of the marker and falls through to the normal link policy). A README’s raw HTML can still mint the marker on a safe internal path, and that’s deliberately kept: it just routes through the host’s pathless resolver instead of the directory-relative one, and both stay internal — neither escapes the app origin. The sanitizer never learns what a wikilink means. The file list and the front door are untouched.

The earlier instinct to call resolution “moderate effort” was wrong: it assumed a file index that turned out to already ship. With that corrected, the whole feature — distinct rendering, pathless resolution, and the ambiguity menu — is a half-day, low-risk change. Transclusion is a deliberate no; heading-scroll is out of scope.