Advanced Rename and Delete Handler

Advanced Rename and Delete Handler

Obsidian updates the links pointing at a note when you rename it, and stops there. The images you pasted into that note stay behind under the old name. Deleting the note leaves them behind entirely, referenced by nothing, in a folder named after something that no longer exists.

This plugin takes over renaming and deleting for the whole vault: links follow the note, the files it owns travel with it, and what a deletion leaves behind is cleaned up on terms you choose.

It is the single owner of that behavior in a vault. Several plugins used to carry their own copy of this handler, and two handlers acting on one rename corrupt links between them. Rather than compete, this plugin checks on load and refuses to run while a plugin that still owns its own handler is installed, naming the ones to update; once they are, it starts on its own.

Demo vault

The documentation is a demo vault. Every feature has a note that explains what it does and why you would want it, with buttons that perform the rename or the deletion and then print the vault as a tree, so you see the effect rather than read a description of it.

Start reading here — it is plain markdown, so it works on GitHub with nothing installed.

A copy of the vault ships with every release. You can access it via any of the following:

1. Running the Advanced Rename and Delete Handler: Open demo vault command.
2. Downloading advanced-rename-and-delete-handler-demo-vault.zip from the Releases. It unzips into a single advanced-rename-and-delete-handler-demo-vault-<version> folder.
3. Browsing its source in demo-vault/ in this repository.

What it does

• Links follow a renamed or moved note, including the display text of a link that was showing the old file name — while a link somebody gave their own words to is left alone. 01 Renaming a note
• Attachments travel with the note that owns them, folder and all, when it is renamed or moved to another folder. 01 Renaming a note
• Deleting a note can clean up after it — the attachments only that note used, and the folder the deletion leaves empty. Off by default, because each option removes something. A Delete empty folders command sweeps the whole vault for the ones already sitting there, left by deletions made before you turned any of this on. 02 Deleting a note
• An attachment two notes share is never deleted with one of them, and can be moved to the note that still uses it rather than left in a folder belonging to a note that is gone. When several notes could adopt it and your priority list settles nothing, the plugin names them and asks rather than guessing. An attachment that is really a folder — a _files tree, a drawing's sidecar folder — moves whole, when your attachment-location plugin says so. 03 Shared attachments
• A drawing stored as .excalidraw.md is treated as an attachment, not a note, along with any other ending you add. 04 What counts as a note
• The plugin can be confined to part of the vault with include and exclude path lists. 05 Limiting the scope

For plugin developers: handing your settings over

A plugin that used to handle renames and deletions itself, and no longer does, can propose the settings it held so a vault keeps behaving the way it did, and can go on reading those settings back afterwards. This plugin owns those settings, so it owns the dialog too: your proposal is shown next to the current values, and the user approves, edits or declines it row by row. Nothing is written unless they press OK.

The API is published through the obsidian-dev-utils cross-plugin registry, which gives you version negotiation, a handle that is revoked when this plugin unloads, and a wait that ends when this plugin loads — rather than a lookup that returns undefined because it ran first.

import { watchPluginApi } from 'obsidian-dev-utils/obsidian/plugin/plugin-api';

const ref = watchPluginApi<AdvancedRenameAndDeleteHandlerApi>({
  apiVersionRange: '^1',
  app: this.app,
  component: this,
  pluginId: 'advanced-rename-and-delete-handler'
});

const api = await ref.whenAvailable();
const result = await api.migrateSettings({
  proposedSettings: {
    shouldHandleRenames: true,
    treatAsAttachmentExtensions: ['.excalidraw.md']
  },
  sourcePluginId: this.manifest.id
});

if (result.isApplied) {
  // Record your own one-shot flag, so the offer is not repeated.
}

• proposedSettings names only what you held. Every member is optional, and a proposal that matches what this plugin already holds is dropped rather than shown, so a user is never asked about a row that would change nothing.
• result.isApplied is false when the user cancelled and nothing was written — do NOT record your migration as done in that case. It is true when they approved, and also when the proposal changed nothing and no dialog was needed.
• The call resolves only once the dialog is closed, so awaiting it is how you learn the answer. Two plugins proposing at once are queued, never stacked.
• A value of the wrong type is refused rather than written, so a mistake surfaces as an error instead of a corrupted data.json.
• The settings you may propose are emptyFolderBehavior, excludePaths, includePaths, notePriorities, shouldDeleteConflictingAttachments, shouldHandleDeletions, shouldHandleRenames, shouldRenameAttachmentFiles, shouldRenameAttachmentFolder, shouldRescueSharedAttachments, shouldUpdateFileNameAliases and treatAsAttachmentExtensions.
• The contract version is 1.1.0 and moves independently of the plugin's own version. Ask for '^1'.
• If you cannot depend on a library version that has the registry, the same object is on the plugin instance as app.plugins.plugins['advanced-rename-and-delete-handler']?.api — untyped, and null until this plugin has loaded.

Reading the settings back

Handing the settings over does not end your interest in them: the same values drive features of your own that have nothing to do with a rename or a delete. Rather than keeping a shadow copy, read them from here.

All three members are synchronous, so you can call them from a checkCallback(isChecking), a settings row's disabled / visible predicate, or a loop over vault files — none of which can await. Hold the ref, not the API object, and read ref.value each time: it is null before this plugin loads and after it unloads, and correct again on a re-enable.

const ref = watchPluginApi<AdvancedRenameAndDeleteHandlerApi>({
  apiVersionRange: '^1',
  app: this.app,
  component: this,
  pluginId: 'advanced-rename-and-delete-handler'
});

// Inside a `checkCallback`, a `visible` predicate, or a loop over vault files.
const api = ref.value;
if (api && !api.isPathIgnored(file.path) && !api.isTreatedAsAttachment(file.path)) {
  const { emptyFolderBehavior, notePriorities } = api.getSettings();
  // ...
}

• getSettings() returns all twelve values above as plain data, read live on every call, so there is nothing to invalidate and nothing to subscribe to. The arrays are copies — writing to one changes nothing here.
• isPathIgnored(path) answers whether this plugin leaves the path alone, per the include and exclude lists.
• isTreatedAsAttachment(path) answers whether the path names an attachment despite its extension — .excalidraw.md being the case that motivated the setting.
• Use the two predicates rather than re-matching the arrays yourself. Every plugin bundles its own copy of obsidian-dev-utils, so running the lists through your copy of the matching code is two copies that can drift apart; asking here keeps the matching in one place.
• These arrived in contract 1.1.0. That is purely additive, so '^1' still gets you them — but a vault running an older release will hand you an API without them, which is what watchPluginApi's shape check is for.

Installation

The plugin is not yet listed in the official Community Plugins repository. Until it is, install it as a beta release.

Beta versions

To install the latest beta release of this plugin (regardless if it is available in the official Community Plugins repository or not), follow these steps:

1. Ensure you have the BRAT plugin installed and enabled.
2. Click Install via BRAT.
3. An Obsidian pop-up window should appear. In the window, click the Add plugin button once and wait a few seconds for the plugin to install.

Debugging

By default, debug messages for this plugin are hidden.

To show them, run the following command:

window.DEBUG.enable('advanced-rename-and-delete-handler');

For more details, refer to the documentation.

Changelog

All notable changes to this project will be documented in the CHANGELOG.

Contributing

Contributions are welcome — see CONTRIBUTING to get set up.

Support

My other Obsidian resources

See my other Obsidian resources.

License

© Michael Naumov