Linking Architecture

Linking Architecture

How links, transclusions, images, and attachments work throughout Steel Notes,

end to end: syntax → editor token model → rendering → indexing → navigation →

lifecycle (rename/move/delete/GC).

Verified against the codebase on 2026-07-30. The [[wikilink]] grammar is

fully retired (tokenizer, classifier, extractors, and renderers recognize only

the forms below); VaultManager.migrateLegacyLinks() converts legacy content

once per vault, gated by a .steel/link-migration-v1 marker

(VaultManager.kt:50-75). History and rationale: LINK_FORMAT_MIGRATION_PLAN.md.

The reference grammar

One markdown syntax family, distinguished only by the URL:

Key asymmetry: **steel:// targets identity (note id), path links target

location.** Ids never change (title renames don't touch the filename), so

note links survive any reorganization with zero content rewriting. Path

targets are only stable because attachments/ is flat and its generated

names (below) are never renamed.

The link title is display-only and may go stale after a rename;

resolution consults the id alone. Titles are sanitized at insertion

([, ], (, ), newlines → space) so they can't break the surrounding

markdown.

The steel:// scheme — SteelUri.kt

shared/src/commonMain/kotlin/com/steelnotes/parser/SteelUri.kt is the single

source of truth: scheme detection (hasScheme), id extraction (noteId —

trims, rejects empty host), builders (noteLink, transclusion,

sanitizeTitle), and the canonical regexes every layer matches through

(noteLinkPattern, transclusionPattern, and per-id variants for whole-vault

rewrites). Never inline a steel:// regex elsewhere — the patterns used to be

four hand-rolled copies that disagreed on case and whitespace.

Two deliberate properties:

never as a file path — nothing tries to open a file named steel://.

There is no OS-registered steel:// URL scheme — the scheme lives only

inside .md files; nothing outside the app can open one.

Vault layout and ids

```

vault/

notes/<id>.md (plus user folders: notes/<folder>/…/<id>.md)

resources/<id>.md quotes/<id>.md

attachments/<YYMMDD-8hex>.<ext> .steel/ (local markers)

```

moveNote — VaultManager.kt:958-999); resources, quotes,

attachments, notes, inbox, .steel are structural, never user

folders.

share-2026-07-20-154839). Ids never contain /.

(model/AttachmentNaming.kt): flat YYMMDD-{8hex}.{ext}. A one-time

vault migration flattened legacy attachment subdirectories and rewrote

the referencing markdown (VaultManager.kt:126, 227-290).

Layer 1 — Editor token model (KMP shared)

shared/src/commonMain/kotlin/com/steelnotes/editor/

MarkerToken (hidden syntax chars), TextToken (visible text with style

flags), and AtomicToken(raw, kind, text, payload) with

Kind { LINK, NOTE_LINK }:

SteelUri).

line exactly — the offset map (resource↔display) is built on it. Any new

link syntax must preserve this.

NOTE_LINK (:216), everything else LINK. A whole-line

!… is not an inline token — transclusions are block-level.

as TRANSCLUSION, other whole-line !… as IMAGE; a malformed steel

target is neither.

Layer 2 — Insertion

<title> (blank title falls back to the id).

on its own line.

NoteLinkPickerView.swift and QuotePickerView.swift deliver (id, title)

through UnifiedEditorViewController to the engine.

inserts !…; photo capture writes bytes to

vault/attachments/ under a generated name, then inserts (:274-281).

On load, the controller hydrates missing attachment bytes from sync (:40).

Layer 3 — Rendering (iOS)

Live editor (ParagraphBuilder.swift)

Hidden-marker WYSIWYG: syntax characters become hidden offset-map segments

(displayLength 0).

NSTextAttachment icon — an .attachment(1,1) map segment, the tested

atomic-cursor primitive — showing the linked note's type icon and color

(via itemLookup, generic note icon as fallback); the title is visible in

blue; the ](steel://id) suffix is hidden. Anchoring the icon on [ keeps

edits near it on the full-rebuild path.

](url) suffix hidden.

targets).

the note surfaces as a "Linked Notes" card below the editor

(UnifiedEditorViewController), ids via TransclusionExtractor; tapping a

card navigates.

Read-only views (InlineMarkdownParser.swift)

Same KMP tokenizer rendered to SwiftUI Text: NOTE_LINK = type icon +

accent title; LINK = accent + underline. Not tappable.

Tap-to-navigate surfaces today: transclusion cards and Resource

table-of-contents rows. Navigation is AppNavigation navPath.append(noteId)

resolved by getNoteById.

Layer 4 — Indexing (two parallel systems)

A. Id-keyed links table (backlinks graph)

despite the column name, target_path holds the note id.

SteelUri.ids(...) over code-stripped prose:

note links → 'reference', transclusions → 'transclusion', structured

refs (Note.resources, Quote.resourceId) → 'structured'.

Markdown path links are not indexed here.

VaultManager.getBacklinks → SharedCoreService.getBacklinks

(SharedCoreService.swift:331). No UI consumes it yet.

B. Path-keyed file_reference table (dependency graph)

ReferenceParser.kt.

body and frontmatter (photo, photos, cover_image, thumbnail).

Steel targets are stored as the bare id; path targets are resolved via

resolveRelativePath (./, ../, else vault-root-relative); external URLs

are excluded; code fences and inline code are skipped.

Layer 5 — Structured frontmatter links

Serialized by NoteSerializer.kt, parsed back by NoteFactory.kt:

the notes-tab companion of a Resource (Note.companionOf / resourceUrl,

Note.kt:36-50). resource_url is stamped once at creation so the raw .md

names a reachable article, not just an opaque id. See COMPANION_NOTES.md.

paths and url.

Both keys are omitted when unset so ordinary notes serialize byte-identically

(no reindex churn).

Layer 6 — Lifecycle behavior

elsewhere go stale (accepted, Obsidian-alias-style). No staleness refresh

exists.

file contents never rewritten. Safe for steel links (id unchanged); would

break body path links, which in practice only target the never-moving

attachments/.

deletes the note's attachments if no other note references them. It does

not rewrite other notes' content — inbound steel:// links dangle

(render fine; navigation target missing). ReferenceRewriter.rewrite /

removeReferences (whole-vault content rewrites incl. frontmatter fields)

exist and are tested but have no production caller — dormant machinery

for id-rewrites/unlinking if ever needed.

union of all references parsed by ReferenceParser (body + frontmatter),

with an mtime safety window, a pending-sync-push exclusion, and a

continuous-orphan grace period before deletion.

No server or CLI parsing of links.

Known warts

1. Nothing is tappable inline — note links, path links, and web links all

render as links but only transclusion cards navigate.

2. Two disjoint index systems (links id-keyed, file_reference

path-keyed) built from two parsers (SteelUri extractors vs

ReferenceParser).

3. Backlinks are computed but never shown.

4. Deleting a note leaves dangling inbound links (the unlink rewriter is dead

code).

5. Body image paths are vault-root-relative while notes live in notes/, so

the raw files don't render in strict external md tooling — see

MD_EXPORT_EVALUATION.md.