Consistent Attachments

Consistent Attachments keeps your vault tidy by moving (or copying) note attachments when notes move between folders.

Why this plugin

In many vaults, attachments drift away from their notes over time:

• notes are moved, attachments stay behind
• shared files are hard to handle safely
• folder structures become inconsistent

This plugin automates the common cases while preserving control for edge cases.

Feature highlights

• Automatically process attachments on note folder moves.
• Support shared attachment handling with skip, copy, or ask.
• Choose destination behavior:
  • follow Obsidian default
  • note subfolder
  • same folder as note
  • fixed vault folder
• Avoid overwrites with automatic numeric conflict suffixes (-1, -2, ...).
• Scan for unreferenced (orphaned) attachments with filter, sort, and trash cleanup.
• Scan for misplaced attachments (still linked but wrong path) with preview and relocate actions.
• View a recent in-memory operation log.
• Run manual actions from command palette and file context menu.

Installation

Community plugins (recommended)

1. Open Settings -> Community plugins.
2. Select Browse.
3. Search for Consistent Attachments.
4. Install and enable the plugin.

Manual installation

1. Download or build these files: main.js, manifest.json, styles.css.
2. Copy them into:
   • <Vault>/.obsidian/plugins/consistent-attachments/
3. Reload Obsidian and enable the plugin.

Quick start

1. Enable Auto-move in plugin settings.
2. Select a target path mode that matches your vault layout.
3. Move a note to another folder.
4. Review moved/copied attachments and open the operation log if needed.

Settings reference

• Enable auto-move: turn automatic processing on note move events on/off.
• Shared attachment strategy:
  • skip: keep shared files in place
  • copy: keep original, create note-local copy
  • ask: prompt for every shared file
• Target path mode:
  • Follow Obsidian default
  • Subfolder of note (configure subfolder name)
  • Same folder as note
  • Fixed vault folder (configure fixed path)
• Delete empty attachment folders: remove note-local attachment subfolders left empty after a move.
• Excluded folders: ignore note moves inside selected paths.
• Show notices: display operation summaries in Obsidian notices.
• Operation log size: max number of entries kept in memory.

Commands

• Move attachments for current note
• Apply attachment layout to vault — scan all notes and move attachments to match the current target path settings
• Find orphaned attachments — unreferenced files only; safe to delete
• Find misplaced attachments — linked files not at the expected path; relocate instead of delete
• Show recent operation log
• Toggle auto-move on/off

Additionally, the file explorer context menu for markdown notes contains:

• Move attachments for this note

Shared attachment behavior

When another note also references the same attachment, the plugin applies your configured strategy:

• Skip: do nothing to the shared file.
• Copy: create a copy at the destination path for the moved note.
• Ask: open a decision modal during the operation.

Conflict handling

The plugin never overwrites existing files. If a destination filename already exists, it appends a numeric suffix:

• image.png
• image-1.png
• image-2.png

Limitations and non-goals

• Link parsing is optimized for standard wiki and markdown links.
• The orphan scan lists only unreferenced attachment candidates. The misplaced scan lists linked files that are not at the expected path for any referencing markdown note (for example after a note move without auto-move). Both use Obsidian's link index plus markdown link parsing; rare edge-case references may still be missed.
• The operation log is in-memory only and resets on reload.
• No cloud service is required; processing is local to your vault.

Troubleshooting

• Attachments are not moved
  • verify Enable auto-move is on
  • check excluded folders
  • note-only renames in the same folder are intentionally ignored
• Attachments stayed behind after moving a note
  • run Find misplaced attachments to review and relocate them, or Apply attachment layout to vault for a full pass
• Unexpected skips
  • check shared attachment strategy
  • inspect the operation log modal
• Conflicts occur often
  • adjust target path mode to reduce filename collisions

Privacy and security

• No telemetry is collected.
• No external network service is required for core functionality.
• File operations stay inside the Obsidian vault.
• Vault access (local only, via Obsidian APIs):
  • Apply attachment layout to vault and auto-reconcile enumerate markdown notes with vault.getMarkdownFiles() and read note content with vault.cachedRead() to resolve linked attachments.
  • Find orphaned attachments enumerates vault files with vault.getFiles(), maps referencers from metadataCache.resolvedLinks and markdown notes, then lists unreferenced attachment candidates.
  • Find misplaced attachments uses the same referencer map and plugin target path settings to list linked files that should be relocated (not deleted).
  • Move attachments for current note only reads the active note and files referenced by that note.
  • Excluded folders in settings are skipped during vault-wide scans.
• Orphan cleanup in the modal moves files to the vault trash via Obsidian's trash API.

Development

Requirements:

• Node.js 18+
• npm

Commands:

npm install
npm run build
npm run lint
npm run dev