obsidian/attachment-unit-folder

Resolves which folder an attachment belongs to when the user has designated folders that must travel as a single unit.

Some formats are really a directory tree rather than a file: a page saved from a browser sits next to a _files/ folder holding its images and stylesheets, an .excalidraw sits next to the images it references. Relocating only the linked file leaves the rest behind and the attachment arrives broken.

This lives in the shared library rather than in one plugin because more than one plugin relocates attachments over the same vault. If they each decided separately what one attachment is, a user with both installed would get a folder kept whole by one and torn apart by the other.

Which is why the designation itself is read from the vault rather than supplied per caller: pass an App and findAttachmentUnitFolderPath walks with whatever an attachment-location plugin published on the patched Vault.getAvailablePathForAttachments, so every plugin decides from one answer. The explicit-predicate form remains for a caller that genuinely owns its own patterns.

Interfaces

Interface	Description
FindAttachmentUnitFolderPathFromAppParams	Parameters for findAttachmentUnitFolderPath, reading the designation published on the vault.
FindAttachmentUnitFolderPathWithPredicateParams	Parameters for findAttachmentUnitFolderPath, walking with a predicate the caller owns.
RebasePathOntoFolderParams	Parameters for rebasePathOntoFolder.

Functions

Function Description

findAttachmentUnitFolderPath Finds the folder that an attachment must travel with. Returns the outermost designated ancestor, not the nearest one. With nested designations, moving the nearest would tear the outer tree in half, which is the failure the whole feature exists to prevent. The vault root is never a unit, however the patterns are written: designating it would make every relocation a no-op at best and a vault-wide move at worst. Passing an App walks with the designation an attachment-location plugin published on the vault; when nobody published one, nothing is designated and the answer is null.

rebasePathOntoFolder Rebases a path from one folder onto another. Used to work out where a linked attachment ends up once its whole unit folder has moved, so the link can be pointed at the file’s new home rather than at where the folder used to be.

Function	Description
findAttachmentUnitFolderPath	Finds the folder that an attachment must travel with. Returns the outermost designated ancestor, not the nearest one. With nested designations, moving the nearest would tear the outer tree in half, which is the failure the whole feature exists to prevent. The vault root is never a unit, however the patterns are written: designating it would make every relocation a no-op at best and a vault-wide move at worst. Passing an `App` walks with the designation an attachment-location plugin published on the vault; when nobody published one, nothing is designated and the answer is `null`.
rebasePathOntoFolder	Rebases a path from one folder onto another. Used to work out where a linked attachment ends up once its whole unit folder has moved, so the link can be pointed at the file’s new home rather than at where the folder used to be.

Types

Type	Description
FindAttachmentUnitFolderPathParams	Parameters for findAttachmentUnitFolderPath. Prefer FindAttachmentUnitFolderPathFromAppParams — it is the form that makes every plugin decide from one published answer.