Skip to content

v0.5.0 — block-scoped links and transclusion

Choose a tag to compare

@verveguy verveguy released this 09 Sep 16:20
· 94 commits to main since this release
ea893a7

Adds Obsidian-style block references, and live transclusion of the block they point at. Purely additive — existing wiki-links are untouched.

[[file#^id]] — link to a block, not a file

A wiki-link can now target one specific block inside a file rather than the file as a whole, using the Obsidian block-reference form. [[notes#^01ABC]] opens notes scoped to that block; [[notes#^01ABC|see this]] does the same with an alias.

![[file#^id]] — transclude it

The ! form renders that block's live, current content inline at the reference site, so edits to the source show up on the next render rather than being copied once.

This needs one new optional host service:

resolveTransclusion(file: string, blockId: string): Promise<string | null>

See docs/editor-api.md. If you inject nothing, or your resolver can't find the reference, the editor renders a clearly marked "unresolved" placeholder — it does not throw. A transclusion cycle is detected and rendered as a "circular transclusion" indicator rather than hanging, and nesting is bounded to a depth of 8.

See ADR-119 for the design, including why the ! marker is detected by sentinel substitution ahead of the wiki-link extension, and how fenced and inline code spans are protected from it.

One known limitation, recorded rather than hidden

[[notes.md#^01ABC]] — a block reference whose target carries an explicit .md extension — round-trips to [[notes#^01ABC|notes.md]], moving the extension into an alias. The content survives and the link still resolves; the source text changes shape once. It is pinned by a known-defects round-trip fixture, so a future fix will show up as a fixture change rather than a surprise.

Nothing else changed for consumers

The export surface is identical. TransclusionNode is registered in editorNodes, and ./nodes exports that array, so a headless consumer building its own editor picks it up with no code change.

scripts/check-lockfile-drift.mjs also landed since 0.4.1 — a weekly check that fails when this repo's lockfile pins a first-party dependency behind what its range already allows. It ships nothing and changes nothing for consumers; it exists because that gap silently withheld three separate fixes in one week.

Upgrading

pnpm add @liminis/editor@^0.5.0

Nothing to change. Implement resolveTransclusion only if you want ![[file#^id]] to render live content.