Skip to content

fix(md-notebook): resolve root-relative images against the vault root - #23746

Merged
iamwhatever merged 2 commits into
mainfrom
fix/notes-root-relative-images
Oct 25, 2026
Merged

iamwhatever merged 2 commits into
mainfrom
fix/notes-root-relative-images

Conversation

@RohanK6

@RohanK6 RohanK6 commented Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

Fixes #23630

Problem / Motivation

Goal: A Notes-app image linked with a leading slash (![a](/images/a.png)) loads from the vault root when that absolute path does not exist.

The Notes preview served any /… image source as an absolute filesystem path and nothing else. A vault that keeps its images at its root and links them root-relative (the Obsidian-style convention) showed every such image as the broken-image alt text.

Why it matters

Vaults imported from Obsidian and similar tools commonly use root-relative image links. Every one of those images renders broken in the Notes app today, so the note reads as missing its diagrams and screenshots.

Not a goal

What changed (motivation → approach → change)

Symptom → cause: resolveNoteImageSrc (website/src/apps/md-notebook/utils.ts) treats any leading-slash source as rooted and requests it verbatim, so /images/a.png is looked up at the filesystem root, never under the vault.

Approach: keep the absolute path as the first request, exactly as today, so a real absolute path still loads on the first try and nothing that works now changes. Only when that load fails, retry the same path once under the open vault's content root, then fall back to the alt text. This matches the issue's expected behavior ("when the absolute path does not exist").

Change:

note body  ![x](/images/a.png)
   │
   ▼
NoteImage  src = /api/file-raw?path=/images/a.png          (unchanged first try)
   │ onError
   ▼
vaultRootImageSrc(rawSrc, vaultRoot)
   │  refuses: . or .. segment (plain, %2e-encoded, backslash-separated),
   │           encoded / or \ (%2f, %5c), NUL (raw or %00), //host
   ▼
NoteImage  src = /api/file-raw?path=<vault root>/images/a.png   (one retry)
   │ onError
   ▼
alt text with the broken-image glyph                         (unchanged)
  • utils.ts: new vaultRootImageSrc(src, vaultRoot) builds the vault-rooted URL, or returns null when the source is not root-relative or any segment could leave the root lexically. A null means no retry, so a traversal source degrades to alt text as before. Each segment is percent-decoded once, checked, and the path is built from those decoded segments (so System%20diagram.png asks for System diagram.png), because /api/file-raw treats path as a literal filesystem path; a segment with a malformed escape is kept as written.
  • vaultRootContext.ts: a React context carrying the vault content root to NoteImage, because images are rendered from inline(), a plain function called by many block renderers.
  • Preview.tsx: new optional vaultRoot prop, provided through that context.
  • MdNotebookPage.tsx: passes vaultContentPath(activeVault) (local path plus subfolder) as vaultRoot.
  • NoteImage.tsx: tracks which source failed; the retry state is keyed on the fallback URL so switching vault or note starts over from the absolute path.

The retry asks /api/file-raw for a path under the vault, nothing a plain absolute source could not already request, and every check on that endpoint (sensitive paths, symlink refusal, image magic number) still applies, which covers symlink escapes out of the vault.

Backwards compatibility

Compatible: the first request for every image is byte-identical to main; the vault-root retry only runs after that request has already failed, and vaultRoot is an optional prop.

Removes nothing: the change only adds a fallback request after a failed load; no path, key, function or behavior that main accepts is removed or narrowed.

Tests

website/src/test/mdNotebookImages.test.tsx:

  • vaultRootImageSrc reads /images/a.png against the vault root, without doubling a trailing slash on the root.
  • No retry without a vault root, or for a relative, remote, ~, Windows-drive or bare / source.
  • Refuses a protocol-relative source (//host/share/a.png).
  • Refuses traversal so the retry cannot leave the vault: /../, nested .., trailing .., . segment, %2e%2e, %2E%2E, half-encoded .%2e, encoded slash %2f, encoded backslash %5c, backslash .., raw NUL, %00.
  • Decodes a percent-encoded file name once (System%20diagram.png → System diagram.png, caf%C3%A9.png → café.png) and keeps a malformed escape (100%.png) as written.
  • Keeps a file name that only contains dots (a..b.png, ..hidden.png).
  • The absolute first try from resolveNoteImageSrc is unchanged.
  • Rendered Preview: absolute path first, then the vault root, then alt text; stops at the vault root when it loads; no retry when the vault root is unknown; a traversal source is never retried under the vault; a relative image is not retried; changing vault starts over from the absolute path.

Local gates: vitest over all 14 md-notebook test files (374 tests) pass; tsc -p tsconfig.app.json and eslint on the changed files are clean; lint:theme-colors, lint:phantom-classes, lint:restyle-ratchet, lint:i18n pass.

Proof: not provable -- frontend test

Manual verification

Rendered the real Preview in an isolated Vite capture page with /api/file-raw answered the way the endpoint would for a vault at /home/me/vault (404 for every path except /home/me/vault/images/diagram.png). Recorded request sequence:

  • before (no vault root, as on main): /images/diagram.png, /../etc/secret.png; both images show alt text.
  • after: /images/diagram.png, /../etc/secret.png, /home/me/vault/images/diagram.png; the diagram loads and the traversal source is never retried under the vault.

Not run in the full desktop app against a real vault.

Screenshots / video

Before (main, dark): the root-relative image falls back to its alt text.

Before, dark

After (dark and light): the image loads from the vault root; the traversal source stays refused.

After, dark

After, light

Related Issues

Fixes #23630. Related: #23623 (the same symptom in the file preview, addressed in #23631).

Sibling sweep

Swept: git grep -nE "resolveNoteImageSrc|file-raw?path" -- website/src
Sibling: website/src/components/markdown/ImgWithFallback.tsx -- tracked in #23623
Sibling: website/src/apps/design-critique/api.ts -- not affected -- builds URLs from picked file paths, not markdown image sources
Sibling: website/src/apps/mochi/panel/panelBridge.ts -- not affected -- serves explicit absolute file paths, no markdown root convention
Sibling: website/src/components/FileRenderers.tsx -- not affected -- previews the opened file by its own path, not a link inside it

Pattern harvest

Not generalizable: the root a leading-slash link means depends on each renderer's context (vault root here, site root in the file preview), so there is no single rule to enforce mechanically.

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.

A note image written as /images/a.png was only ever served as an absolute
filesystem path, so a vault that keeps images at its root and links them
with a leading slash (the Obsidian convention) showed them broken.

NoteImage now tries the absolute path first, unchanged, and on a load
error retries the same path once under the open vault's content root
before falling back to the alt text. The retry is built by
vaultRootImageSrc, which refuses any candidate with a . or .. segment
(plain, percent-encoded or backslash-separated), an encoded separator,
a NUL byte, or a protocol-relative source, so the second try cannot leave
the vault. It goes through the existing /api/file-raw endpoint and its
checks; no route changes.

Fixes #23630
@RohanK6
RohanK6 requested review from a team and KiroCrewCaptain as code owners October 24, 2026 14:08
@RohanK6
RohanK6 requested a review from iamwhatever October 24, 2026 14:08
@github-actions

github-actions Bot commented Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks: the fix is additive (the absolute path is tried first, then one retry under the vault root), traversal is refused before the retry, and three committed screenshots show the rendered change.

Notes

  • If a file exists at the same absolute path outside the vault (e.g. /images/a.png), the absolute path wins over the vault copy. The description intends this, so the issue's wording is the contract. A follow-up could try the vault root first, but that would change what main loads today.

[DESIGN-REVIEWED] 15ea419

Description read

[DESCRIPTION-READ] d34111fd5b941d68360e5411bbea66866063b6e55f7e9f1ab431d72916cddf2f

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 Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 15ea4194c23601f8b191b29212dc8d475f7461e4 — 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. The fallback fixes the cause named in #23630, adds no route, and its one new public function has one real consumer.

What this change ships

Inventory (5 items) — 5 justified

Intent: let a Notes-app vault whose images are linked root-relative (/images/a.png) display those images. FIX.

  1. A root-relative image that fails as an absolute path now retries once under the open vault's content root — justified
  2. Images whose root-relative path climbs out of the vault (.., encoded separators, NUL, //host) still fall back to alt text with no retry — justified
  3. Percent-encoded file names are decoded once on the vault-root retry (System%20diagram.png → System diagram.png) — justified
  4. A new optional vaultRoot prop on Preview, carried to the image by a new context and fed by MdNotebookPage — justified
  5. Before and after screenshots committed under temp-screenshots/ (the evidence path .gitignore and ux-review.yml expect) — justified

[FIRST-PRINCIPLES-REVIEWED] 15ea419

Description read

[DESCRIPTION-READ] 8e7f7855ce615973efc6616a2795a10dd5efce3274c67372a6056dbc272912a1

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 Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

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

UX-Verdict: PASS

Nothing blocks: the change adds no control, label or string, and the before and after screenshots show the root-relative image now loading.

[UX-REVIEWED] 15ea419

Description read

[DESCRIPTION-READ] 3f7ede2997c0cfc32526d36004d26b8ccbe42923b79e98807c3fb9bdd0e79a51

That sha256 names everything this verdict read: the PR description, plus the 6 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 Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 15ea4194c23601f8b191b29212dc8d475f7461e4 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 15ea419

Verdict parsed from the review's SHA-scoped output markers for commit 15ea4194c23601f8b191b29212dc8d475f7461e4.

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

@github-actions

github-actions Bot commented Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 15ea4194c23601f8b191b29212dc8d475f7461e4 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 15ea419

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

The vault-root retry decoded each segment only to validate it, then sent
the still-encoded text to /api/file-raw, which reads path as a literal
filesystem path. A link such as /images/System%20diagram.png therefore
asked for a file literally named System%20diagram.png and fell back to
alt text. Build the path from the decoded, validated segments instead.

Fixes #23630
@RohanK6 RohanK6 closed this Oct 24, 2026
@RohanK6 RohanK6 reopened this Oct 24, 2026
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Oct 24, 2026

@iamwhatever iamwhatever left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

APPROVE at 15ea4194c23601f8b191b29212dc8d475f7461e4.

The first request for every image is unchanged. Only after it fails does NoteImage retry once under the vault root, then fall back to the alt text. vaultRootImageSrc refuses ./.., encoded separators, NUL and protocol-relative sources before it builds the path, and it builds the path from the segments it checked. No route or server check changes, and /api/file-raw still applies its own checks. The Design note about an absolute file winning over the vault copy matches the issue's contract and is informational.

All AI lanes are clean and there are no deferred items. Sensitive Change Review and Publish readiness signal are still queued; protected auto-merge should wait for them.

— crew-pr-reviewer (r125)

@iamwhatever
iamwhatever enabled auto-merge (squash) October 25, 2026 07:57
@iamwhatever
iamwhatever merged commit efc8f03 into main Oct 25, 2026
169 of 237 checks passed
@iamwhatever
iamwhatever deleted the fix/notes-root-relative-images branch October 25, 2026 07:57
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 25, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Notes app: root-relative images (/images/…) do not resolve against the vault root

2 participants