Skip to content

feat(md-notebook): resolve relative obsidian embeds inside the vault - #31673

Merged
bolichen97 merged 1 commit into
mainfrom
fix/10197-rest-relative-embeds
Nov 7, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/10197-rest-relative-embeds

Conversation

@bolichen97

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A note shows an Obsidian image embed written in Obsidian's relative link format (![[../assets/a.png]], ![[./a.png]]) as the picture it names, as long as that file is inside the vault.

Obsidian can be set to write links as a "relative path to file". Its embeds then look like ![[../assets/diagram.png]] or ![[./diagram.png]], read from the note's own folder. Since #31101 the Notes app renders ![[file.png]] embeds, but it refuses any target with a . or .. segment, so every embed in such a vault shows the missing-image glyph even though the file is right there.

Why it matters

A vault kept in Obsidian with relative links writes every pasted screenshot this way. Attached to Kiro Crew, all of those images are missing at once, and the only workaround is rewriting every embed by hand, which breaks the vault for Obsidian.

Not a goal

  • Reading attachmentFolderPath from .obsidian/app.json and the vault-wide lookup by a unique file name. Both need the backend to read vault configuration or list vault files, so they stay open on Notes app: resolve Obsidian image embeds and attachment paths in mixed-syntax vaults #10197.
  • Climbing out of the vault's configured subfolder: the folder the vault is scoped to is the ceiling, the same root the other embed tries use.
  • Normalising a .. in the middle of a path that does not start with ./ or ../ (sub/../a.png): Obsidian never writes that, so it keeps asking for nothing.
  • Changing the order of the tries for a target without a leading ./ or ../.

What changed (motivation → approach → change)

An embed whose target starts with ./ or ../ now renders the file it names, read from the note's folder, and asks for nothing once it would climb above the vault root.

Target Where it is looked for
./a.png, ../assets/a.png (also with \) the note's folder only, one try; nothing when it climbs above the vault root
a.png, assets/a.png unchanged: the vault root, then beside the note
absolute, or a ./.. segment anywhere else unchanged: nothing

The approach adds no resolver and no new request. noteRelativeSegments in utils.ts walks the target's segments from the note's folder, as segments under the vault root, and returns null the moment a .. would leave the root. NoteEmbed in NoteImage.tsx hands that result to the existing vaultRootImageSrc, so the same checks still apply to the one path it asks for (no dot segment left, no NUL, no hidden separator), and the guarded /api/file-raw stays the only way image bytes are read.

The Notes spec, docs/system-specs/modules/md-notebook.md, states the relative format in its Images paragraph.

Backwards compatibility

Compatible: the only embeds that render differently start with ./ or ../ and stay inside the vault; they asked for nothing before. Every other target makes the same requests as on main.

Removes nothing: the diff adds one helper and one branch in NoteEmbed; no path, key, route or function goes away.

Tests

website/src/test/mdNotebookImages.test.tsx, in md-notebook/Preview Obsidian embeds:

  • reads a ./ or ../ target from the note folder alone, only inside the vault: from /vault/notes, ../assets/a.png, ./b.png and ..\d.png ask for /vault/assets/a.png, /vault/notes/b.png and /vault/d.png; a failed relative embed makes no second try; sub/../c.png still asks for nothing. Red on origin/main's NoteImage.tsx, green on this head.
  • The backslash row of never requests a %s target now climbs two levels (..\..\a.png), because one level from /vault/notes is inside the vault and resolves by design. The row still pins that a backslash .. cannot leave the vault.

Proof: not provable -- frontend test (prove.py runs Python only)

All 436 tests in the 17 Notes test files pass. Determinism: npx vitest run src/test/mdNotebookImages.test.tsx --sequence.shuffle --sequence.seed=<7919, 15838, 23757, 31676, 39595> passed 64 of 64 each time. The new test uses no timers, network or shared state.

Manual verification

Rendered the built SPA in Chromium with the Notes API and /api/file-raw stubbed (the shared website/scripts/lib capture fixtures), a note at projects/network/vpc-topology.md holding ![[../assets/topology.svg|480]], ![[./subnets.svg]] and ![[../../../outside.svg]]. The page asked /api/file-raw for exactly <vault>/projects/assets/topology.svg and <vault>/projects/network/subnets.svg, and nothing for the one that climbs out. Clicking an embed opened its source line in the block editor.

Screenshots / video

A ../ embed with a width, a ./ embed, and one that climbs out of the vault (kiro-dark):

Relative embeds rendered

Clicking the ../ embed opens its source line in the block editor:

Click on a relative embed opens its source line

Related Issues

Part of #10197

Sibling sweep

N/A — a feature PR, not a fix.

Pattern harvest

N/A — a feature PR, not a fix.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributed under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 6, 2026 19:04
@bolichen97
bolichen97 requested a review from Zedmor November 6, 2026 19:04
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 6, 2026
@bolichen97
bolichen97 enabled auto-merge (squash) November 6, 2026 19:13
@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 466ee6405c57fb140f032f396159c0b06e6afe49 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks. Relative embeds go through the existing vaultRootImageSrc and the guarded /api/file-raw, so this adds no new request path. noteDir and vaultRoot are both built from vaultContentPath, so stripping the vault-root prefix in noteRelativeSegments is safe.

Notes

  • noteRelativeSegments only works if noteDir starts with vaultRoot. Today one caller, MdNotebookPage.tsx:129-132, guarantees that. A later caller passing a noteDir built some other way would silently get the wrong segments, so check the prefix in the helper or keep the two derivations next to each other.

[DESIGN-REVIEWED] 466ee64

Description read

[DESCRIPTION-READ] 467f8d900eb97d7402cbcc6dec21a92cb915cd41194a52a137a494e606a3b75a

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 466ee6405c57fb140f032f396159c0b06e6afe49 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Nothing blocks. Every item renders an image the vault already holds and that Obsidian's relative-link setting writes. The rewritten backslash pin is declared, and it still checks that a backslash .. cannot leave the vault.

What this change ships

Inventory (7 items) — 7 justified

Intent: show Obsidian embeds written in relative link format (![[../assets/a.png]]) as the picture they name when the file is inside the vault. ADDITION.

  1. A ./ or ../ embed now shows its picture, read from the note's folder — justified
  2. Such an embed is looked up in one place only, with no fallback to the vault root — justified
  3. A relative embed that climbs above the vault root still shows the missing-image glyph — justified
  4. ..\ with backslashes is treated the same way as ../ — justified
  5. The test row for a backslash .. now climbs two levels (..\..\a.png) instead of one — justified
  6. The Notes spec's Images paragraph describes the relative format — justified
  7. New exported helper noteRelativeSegments in utils.ts, with one consumer (NoteEmbed) — justified

[FIRST-PRINCIPLES-REVIEWED] 466ee64

Description read

[DESCRIPTION-READ] ca4a974a5d63bdaaf2d7ea78fc65e6f33395d7c967e05c7776d88cf99cc6ebee

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

UX-level review of 466ee6405c57fb140f032f396159c0b06e6afe49 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

UX-Verdict: PASS

Nothing blocks. The PR adds no new control or string; it only renders ./ and ../ embeds that showed the missing-image glyph before, and shot-01 shows both resolving.

Notes

  • An embed that climbs out of the vault still shows the bare missing-image glyph ("outside.svg"). The blind reader could not tell "broken or blocked on purpose". A short caption like "Outside the vault" on that fallback would answer it. That's for a follow-up, since this PR doesn't change the fallback.

[UX-REVIEWED] 466ee64

Description read

[DESCRIPTION-READ] 1e084e5743d782c008c8aa8efce8d587602993f236a5cd70b579179cd7b13fdb

That sha256 names everything this verdict read: the PR description, plus the 5 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 466ee6405c57fb140f032f396159c0b06e6afe49 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 466ee64

Verdict parsed from the review's SHA-scoped output markers for commit 466ee6405c57fb140f032f396159c0b06e6afe49.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 466ee6405c57fb140f032f396159c0b06e6afe49 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 466ee6405c57fb140f032f396159c0b06e6afe49 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 466ee64

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 466ee6405c57fb140f032f396159c0b06e6afe49 false-positive: <reason, 20 to 500 characters>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 6, 2026
@bolichen97
bolichen97 force-pushed the fix/10197-rest-relative-embeds branch from 695c7ca to f4119d1 Compare November 6, 2026 21:37
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/system-specs/modules/ (artifacts.md, dashboard-token-auth.md, learn-cron-dashboard.md, memory-skills-hooks.md, slack-gateway.md, workflows.md) since this head went green (f9e8bdf -> ea5dedb); CI re-running.

The new base carries #31625, which fixes the test_the_package_stays_within_its_line_budget red on Backend Tests shard 2 (Linux and Windows) that this head picked up from main (#31648). The commit is unchanged by the rebase.

[operator: bolichen97]

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 6, 2026
An Obsidian vault set to the "relative path to file" link format writes
its embeds as ![[../assets/a.png]] or ![[./a.png]]. The Notes app
refused any embed with a dot segment, so those images showed as
missing even though the file sits in the vault.

A target that starts with ./ or ../ is now read from the note's folder
alone, and still asks for nothing once it climbs above the vault root.
Every other target keeps its two tries (vault root, then the note's
folder) and its refusal of absolute paths and dot segments.

Part of #10197
@bolichen97
bolichen97 force-pushed the fix/10197-rest-relative-embeds branch from f4119d1 to 466ee64 Compare November 7, 2026 02:01
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/system-specs/modules/ (29 specs beside md-notebook.md) and website/src/test/ since this head went green (ea5dedb -> 42f45e3); CI re-running.

The new base carries #31803, which fixes the test_only_the_allowed_workflows_use_pull_request_target red on Backend Tests shard 7 (Linux and Windows) that this head picked up from main (#31396); Coverage Gate and PR Readiness were failing closed on it. The five AI review lanes on the old head reached no verdict (the CI token hit its rate limit), so they re-run on this push. The commit is unchanged by the rebase.

[operator: bolichen97]

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention labels Nov 7, 2026

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved for the on-call. Review lanes pass on 466ee64, no conflict, no open change request.

@bolichen97
bolichen97 merged commit d6b70dc into main Nov 7, 2026
97 of 106 checks passed
@bolichen97
bolichen97 deleted the fix/10197-rest-relative-embeds branch November 7, 2026 07:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

readiness: passed Eligible automated validation passed for the current revision

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants