README file from
GithubSmart Rename
Rename a note in Obsidian and every link to it is rewritten — including the words your reader sees. A sentence that read "as covered in [[Project brief]]" silently becomes "as covered in [[2026 Q3 plan]]", and prose you wrote carefully now says something you did not write.
This plugin renames the note and keeps the old title as the link's display text, so [[Old title]] becomes [[New title|Old title]] and your sentences still read the way you wrote them. The old title is also kept as an alias, so anything still looking for it finds it.
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 a note ready to rename and backlinks ready to watch.
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:
- Running the
Smart Rename: Open demo vault command. - Downloading
smart-rename-demo-vault.zipfrom the Releases. It unzips into a singlesmart-rename-demo-vault-<version>folder. - Browsing its source in
demo-vault/in this repository.
What it does
- Backlinks keep their old display text.
[[Old title]]becomes[[New title|Old title]], and a link that already had display text you chose is left alone — a plain rename was always right for those. Every link form, before and after, is worked through in the vault. 01 Smart rename - The old title becomes an alias, so searches and links using it still resolve — unless you untick it for that one rename. 01 Smart rename
- Every step is a checkbox in the rename prompt, pre-ticked from your settings, so a single rename can skip the alias, the header or the link rewrites without a trip to Settings. 01 Smart rename
- Invalid characters are handled, rather than the rename being refused, when the title you want cannot be a file name. 02 Invalid characters
- A linked note can be renamed from where you link to it. Put the cursor on a link, run the command, and the note that link points at is smart-renamed — you never open it. Works on wikilinks, markdown links, embeds and frontmatter links alike. 03 Rename the link target
- The first header and a frontmatter title key can be kept in sync with the new name. 04 Settings
- Obsidian's own renames ask what they are for. Renaming a note through its inline title, the file explorer, F2 or a Rename... menu item offers to sync the frontmatter
titleand the first H1 to the new name (the default), to also keep the previous name, or to rename the file only. Renames made by other plugins, by sync or by scripts never ask. Works on mobile too. 05 Rename intent
See also
| Plugin | Features | How Smart Rename differs |
|---|---|---|
Alias Picker |
Alias-rename backlink updates; alias picker and overview | Different trigger: note rename rather than alias rename |
Link with alias |
Writes link display text and target aliases at link creation; no rename/backlink rewrite | Different trigger: note rename; rewrites existing backlinks |
Update Title on Rename |
Automatic filename-to-title sync; preserves custom titles; no backlink/alias/header edits | Broader rename handling: backlinks, aliases and headers |
Last searched for similar plugins on 2026-10-26.
Installation
The plugin is available in the official Community Plugins repository.
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:
- Ensure you have the BRAT plugin installed and enabled.
- Click Install via BRAT.
- An Obsidian pop-up window should appear. In the window, click the
Add pluginbutton once and wait a few seconds for the plugin to install.
Debugging
By default, debug messages for this plugin (id: smart-rename) are hidden.
If you need to enable them 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
Filing an issue (for AI agents and humans)
Open issues through the issue forms, not as blank issues.
To report a bug from inside Obsidian, run the Smart Rename: Report a bug command. It opens the bug form with the plugin version, the Obsidian version and your operating system already filled in.
Filing from the CLI or the API (gh issue create --body, or an AI agent filing for you) skips the form, and gh issue create --template cannot load an issue form. In that case, open the matching form in .github/ISSUE_TEMPLATE/, copy every field as a ### <label> heading in the form's order, and fill in each one. Always state the plugin version, the Obsidian version and your operating system.