Virtual Mount

by zou
5
4
3
2
1
Score: 50/100

Description

Show a real folder or note as a virtual subfolder anywhere in the Obsidian file explorer. Nothing is moved, copied, or symlinked.

Reviews

No reviews yet.

Stats

1
stars
63
downloads
0
forks
9
days
3
days
3
days
0
total PRs
0
open PRs
0
closed PRs
0
merged PRs
0
total issues
0
open issues
0
closed issues
9
commits

Latest Version

4 days ago

Changelog

挂载现在会跟着改名和移动走

重命名或移动源文件夹之后,虚拟挂载不会再「指向一个已经不存在的路径」。插件运行期间的改动会立即跟随;插件没运行时的改动,会在下次启动时按内容指纹自动找回。

更新内容

  • 修复:挂载跟随改名 / 移动。插件运行期间重命名、移动源文件夹或挂载点时,路径、自动推导的显示名和排序位置一起更新;你自己填写的显示名保持不动。
  • 新增挂载索引 mounts.index.json(与 data.json 同目录):记录每个挂载最后一次的路径和内容指纹。插件没运行时发生的改名 / 移动会在启动时自动重新关联;data.json 丢失时也能用索引恢复挂载。
  • 安全策略:只有唯一匹配才重新绑定;同一项目的多份副本同时存在时放弃,不改动配置。挂载点永远不会被找回进它自己的源目录内部。
  • 修复:与真实目录混排后挂载行会乱闪。核心重绘时改为在同一个任务内、浏览器绘制之前同步补注入,并复用被清掉的同一个节点(已展开的子目录不会回到折叠态);只有内容签名变化时才重建节点。
  • 设置页:源路径失效的挂载会标出「路径不存在」,并新增「重建挂载索引」按钮。

安装

  • 社区插件商店:设置 → 第三方插件 → 浏览 → 搜索 Virtual Mount(商店同步可能有延迟)。
  • 手动安装:下载下方的 main.js、manifest.json、styles.css,放进 <你的仓库>/.obsidian/plugins/virtual-mount/,重启 Obsidian 后在「设置 → 第三方插件」里启用。
  • BRAT:添加 ko-Ani/obsidian-virtual-mount 即可跟进后续版本。

完整更新日志见 CHANGELOG.md。

Mounts now follow renames. Renaming or moving the source folder (or the mount point) while the plugin is running updates the path, the automatically derived display name and the sort position together; a display name you typed yourself is left alone.

A new mount index mounts.index.json records each mount's last known paths and a content fingerprint, so renames and moves that happen while the plugin is not running are re-linked at startup — and the index can restore the mounts if data.json is lost. Only a unique fingerprint match is accepted, so two identical copies of a folder leave the configuration untouched.

Also fixed: no more flicker when mounts are sorted together with real entries. A core repaint is now repaired synchronously in the same task, before the browser paints, by re-inserting the very same node, so expanded subfolders keep their state. The settings tab flags broken paths as "Path missing" and adds a "Rebuild mount index" button.

Install from Settings → Community plugins → Browse → search “Virtual Mount”, by copying main.js, manifest.json and styles.css into <vault>/.obsidian/plugins/virtual-mount/, or with BRAT (ko-Ani/obsidian-virtual-mount).

README file from

Github

Virtual Mount

Show a real folder (or a single note) as a virtual subfolder anywhere in the file explorer — nothing is moved, copied, or symlinked.

中文文档

Release Downloads Obsidian Platform License

Install · Usage · How it works · Compatibility · Limitations


What it looks like

Disk (the only real copy)          Obsidian file explorer
03 References/Project A/           01 In progress/
├── alpha.md            ──────▶    ├── meeting-notes.md
├── beta.md                        └── Project A ↪     ← virtual mount
└── subfolder/                         ├── alpha
                                       ├── beta
                                       └── subfolder

The virtual entry looks and behaves like a native folder: click a note and the real file opens, edits show up in both places instantly, and adding or deleting files in the source folder is reflected in the mirror. No folder is created on disk — the mapping lives in the plugin's own data.json.

In one sentence: the file exists once; the virtual location is just an extra node drawn into the file explorer. Rename, create and delete act directly on the real file.

Features

Feature Details
📁 Folder mirror Mount a whole folder under any other folder; the tree follows the source live (create / delete / rename).
📝 Single-note mounts Put one note in several places at once — every occurrence points to the same real file.
🖱️ Mount from the context menu Right-click (long-press on mobile) any folder → Mount as virtual folder…, pick the target and edit the display name.
🧩 Native source menu Right-click a virtual entry and get the same menu as the real folder or note: new note, new folder, rename, move, copy, delete. Every action operates on the source.
🎨 Native look Reuses the core tree classes (tree-item, tree-item-self, tree-item-flair…), so themes and hover states apply.
🔄 Rename tracking Renaming or moving the source (or the target folder) updates the mount immediately. A small index file also re-links mounts whose rename happened while the plugin was not running.
🪶 Zero disk footprint No directories, no symlinks, no junctions, no duplicated files.
📱 Desktop and mobile Same code path; the long-press menu and clipboard fallback work in the mobile app.

When it's useful

  • PARA / Zettelkasten: a reference folder lives in one place but has to show up under both “In progress” and “Archive”.
  • One asset, many entry points: templates, attachments and media libraries appear in every project folder while the files stay in one place.
  • No re-organising: keep the existing folder structure and mount a few views on top of it.
  • Reused notes: the same checklist appears under “This week” and a project — edit either one and it is the same note.

Installation

Option 1 — community plugins (recommended)

Settings → Community plugins → Browse → search “Virtual Mount” → Install and enable.

Option 2 — BRAT

Add ko-Ani/obsidian-virtual-mount as a beta plugin; updates can then be installed from inside Obsidian.

Option 3 — manual

  1. Download main.js, manifest.json and styles.css from the latest release.
  2. Put them in <your vault>/.obsidian/plugins/virtual-mount/.
  3. Reload Obsidian and enable Virtual Mount in Settings → Community plugins.

Usage

Mount a folder

  1. Right-click (long-press on mobile) a folder → Mount as virtual folder….
  2. Mount to picks the parent folder of the virtual entry; leave it empty for the vault root.
  3. Display name can be changed now or later; press Mount.

Right-clicking a note shows Mount as virtual note… instead.

The settings tab has the full editor (type, source, target, name), a list of mounts with per-mount enable toggles, and display options:

Option Effect
Folders before notes Order inside virtual folders only. The mount itself is inserted among the target folder's real entries by name.
Show the ↪ badge Marks virtual entries so they're easy to tell apart from real ones.
Reveal real location on open After opening a file from a virtual entry, scroll the native explorer to its real path.
Max items per virtual folder Larger folders are truncated with a “N more” hint.

Commands (Ctrl/Cmd+P):

  • Add virtual mount…
  • Mount the current note to…
  • Mount the current note's folder to…
  • Refresh virtual mounts

Interactions

Action Result
Click a virtual note Opens the real file (Ctrl/Cmd+click or middle-click for a new tab).
Click a virtual folder Collapse / expand. Subfolders start collapsed and load only when opened; expanded state is remembered, just like native folders.
Right-click / long-press a virtual entry The native menu of its source folder or note: new note, new folder, rename, move, make a copy, delete…
Right-click / long-press a mount root The same menu plus Reveal real location, Copy real path and Remove this mount.

How it works

Obsidian's file index is built by scanning the vault: TFile.path is the real path, and no API can add a virtual path to that index. Obsidian also explicitly ignores intra-vault symlinks, because two copies of the same file would make [[wikilinks]] ambiguous (help).

So this plugin is a view layer: it reads real TFolder data and injects equivalent nodes into the native file explorer. The virtual path is visual only — the file always keeps its real path, which is exactly why edits stay in sync.

Obsidian 1.6+ renders the file explorer with a virtualized tree: setChildrenInPlace() replaces the children of .nav-folder-children on scroll. To keep mounts in normal file-name order, the plugin still puts the mount rows into that very list instead of a separate container that could only sit at the top:

  1. finds the real folder element via data-path on its title,
  2. inserts each mount row directly into .nav-folder-children, at its sorted position among the real siblings (folders first, then numeric-aware name comparison) — a mounted folder appears where its name belongs, not always first,
  3. rebuilds a row only when its source, display name or badge setting changed; a core repaint (scroll / expand / sort change) clears the row together with the real children, and the MutationObserver re-injects the same node synchronously in the same task, before the browser paints — so the row does not visibly disappear and expanded subfolders keep their state,
  4. stops propagation on click / auxclick / contextmenu so the core's delegated handlers never see virtual rows.

Rename tracking and the mount index

Mounts are stored as path strings, and Obsidian files have no stable id. Live renames are handled by the rename event: the plugin rewrites source / under, updates an automatically derived display name, and re-sorts the row. A display name you typed yourself is left untouched.

Events are missed when a folder is renamed while Obsidian is closed or the plugin is disabled. To cover that, the plugin keeps .obsidian/plugins/virtual-mount/mounts.index.json next to data.json. For every mount it records the paths, the display name and a content fingerprint of the source folder (the sorted names of its direct children) and of the target folder. At startup, any mount whose path no longer resolves is looked up by that fingerprint:

  • only a unique match is accepted — two identical copies of a project leave the mount untouched instead of guessing;
  • the target folder is never re-linked into the mount's own source tree;
  • if data.json is lost (reinstall, new device), the index is used to restore the mounts.

The index is a mirror and recovery aid, not a second source of truth: data.json always wins, and a broken or outdated index is ignored. Rebuild in the settings tab refreshes it by hand.

The file-menu workspace event is used to add the right-click item, filtered to the file-explorer-context-menu source. For a virtual entry, the plugin hands the real TAbstractFile back to the file explorer view's own onFileContextMenu(), so the menu is generated by core with the exact source as its target; plugin items are appended through a one-shot file-menu listener. On recent Obsidian versions core anchors a menu to the real tree row and auto-closes it when that row is not visible, so the plugin temporarily hides that row association while the menu is built and restores it immediately afterwards. If that internal method is ever unavailable, a small built-in menu (reveal / copy path / remove mount) is used instead.

Mobile

The mobile app runs the same bundle and the same tree DOM, so mounts render identically. Long-press opens the same context menu, and “Copy real path” falls back to execCommand where navigator.clipboard is unavailable.

isDesktopOnly is false.

Compatibility

Item Details
Minimum Obsidian 1.6.0+
Platforms Desktop (Windows / macOS / Linux) and mobile (iOS / Android)
Tested 1.14.5, plus earlier 1.8.x
Verification Tree DOM and menu behaviour checked against the shipped obsidian.asar

Limitations

  • Drag-and-drop is not supported. Drag the real entry instead. Rename / delete / new note / new folder are available from the virtual entry's native source menu and act on the real file.
  • Virtual paths are not linkable. [[01 In progress/Project A/alpha]] will not resolve; links always use the real path.
  • Not in search, Quick Switcher or Graph — those read the index, which only knows real paths.
  • Ascending name order. Mounts are placed by display name with folders first; if the core is set to Z→A or time-based sorting, the mount rows do not reorder with it.
  • Re-linking is best-effort. A missed rename is resolved only when the source folder's fingerprint matches exactly one folder in the vault. With two identical copies it gives up and the mount stays broken (the settings tab marks it), rather than guessing.
  • Upgrade risk. This depends on core DOM structure; a major Obsidian update may need an adaptation.

Development

pnpm install
pnpm dev      # watch build
pnpm build    # typecheck + production bundle -> main.js
pnpm test     # jsdom tests: DOM injection, plugin entry, i18n

The DOM tests replicate the real 1.8.x tree structure extracted from app.js, including the virtualized-children behaviour.

License

MIT


If it saved you a few file moves, a ⭐ is the best way to say thanks.

Changelog: CHANGELOG.md · 中文说明: README.zh.md