Obsidian Link Updater

A powerful Obsidian plugin that helps you fix dangling links (wikilinks to non-existent notes) by finding them and redirecting all references to existing notes.

The Problem

When writing notes in Obsidian, you sometimes create a link to a note that doesn't exist yet like [[dangling-link]]. Obsidian helpfully shows this as an option when searching and lets you create it. But what if you just misspelled the link and a note like [[this-dangling-link]] already exists? You now have to create dangling-link and merge it with this-dangling-link to "repair" the references.

The Solution

Link Updater makes this process simple:

1. Invoke the "Update dangling link" command
2. Select a dangling link from the list (with reference counts)
3. Choose an existing file to redirect the references to
4. All references across your entire vault are updated automatically

Features

• Find Dangling Links: Automatically scans your vault for wikilinks that don't resolve to existing files
• Reference Counts: Shows how many references exist for each dangling link (e.g., "my-note (5 references)")
• Vault-Wide Updates: Updates ALL references across all files in your vault at once
• Preserve Display Text: Maintains link aliases like [[old-link|Custom Display]] → [[new-link|Custom Display]]
• Folder-Aware: Respects folder paths - [[folder/note]] is treated differently from [[note]]
• Smart Caching: Uses intelligent caching with auto-invalidation for performance
• Safe Updates: Uses Obsidian's native file modification API (fully compatible with Obsidian's undo)

Installation

Manual Installation

1. Download the latest release from the Releases page
2. Extract the files main.js and manifest.json from the zip
3. Create a folder named obsidian-link-updater in your vault's .obsidian/plugins/ directory
4. Copy main.js and manifest.json into the new folder
5. Reload Obsidian
6. Go to Settings → Community plugins → Installed plugins
7. Enable "Link Updater"

Development Installation

If you want to build from source or contribute to development:

# Clone the repository
git clone https://github.com/felixscherz/obsidian-link-updater.git
cd obsidian-link-updater

# Install dependencies
npm install

# Build the plugin
npm run build

# Or run in development mode (watches for changes)
npm run dev

# Symlink to your vault for testing
./symlink-plugin.sh /path/to/your/vault

After symlinking, enable the plugin in Obsidian's settings and reload (Cmd/Ctrl+R) after making code changes.

Usage

Basic Workflow

1. Open the Command Palette (Cmd+P on Mac, Ctrl+P on Windows/Linux)

2. Search for "Update dangling link" and select it

   • Alternatively, you can set a custom hotkey in Settings → Hotkeys

3. Select a Dangling Link

   • The modal shows all dangling links with reference counts
   • Example: my-misspelled-note (3 references)
   • Use the search box to filter links
   • Navigate with arrow keys, select with Enter

4. Choose a Target File

   • The second modal shows all existing files in your vault
   • Search and select the file you want to redirect to
   • Navigate with arrow keys, select with Enter

5. Done!

   • All references are updated instantly
   • You'll see a confirmation: "Updated X references from [[old]] to [[new]]"

Example Scenario

Let's say you have these files:

• project-notes.md contains: See [[poject-notes]] for more info
• ideas.md contains: Link to [[poject-notes]]

Notice the typo: poject-notes instead of project-notes.

Using Link Updater:

1. Run "Update dangling link" command
2. See poject-notes (2 references) in the list
3. Select it
4. Choose project-notes from the file list
5. Both files are updated to reference [[project-notes]]

Link Format Handling

The plugin handles various wikilink formats:

Original Link	Target	Result
[[old-note]]	new-note	[[new-note]]
[[old-note|Display Text]]	new-note	[[new-note|Display Text]]
[[folder/old-note]]	folder/new-note	[[folder/new-note]]
[[folder/old|Custom]]	other/new	[[other/new|Custom]]

Note: The plugin only updates wikilink format [[link]]. Markdown links [text](link.md) are not currently supported.

Folder Paths

The plugin respects folder paths explicitly:

• [[folder/note]] only matches files in that specific folder path
• Uses Obsidian's built-in link resolution for accuracy
• Handles relative and absolute paths correctly

Performance

• Caching: Dangling links are cached after the first scan
• Auto-Invalidation: Cache automatically refreshes when files change
• Debouncing: Batch file changes are handled efficiently (500ms debounce)
• Large Vaults: Tested and optimized for vaults with hundreds of files

Compatibility

• Minimum Obsidian Version: 0.15.0
• Desktop & Mobile: Works on both desktop and mobile platforms
• Safe: Uses Obsidian's native APIs - fully compatible with:
  • Obsidian's undo/redo
  • Git version control
  • Sync plugins
  • Backup systems

Troubleshooting

No dangling links found

If you expect to see dangling links but the plugin says "No dangling links found":

• Make sure you're looking for wikilinks [[link]], not markdown links [text](link.md)
• Check if the links actually don't resolve (they show in purple in Obsidian)
• Try reloading Obsidian to refresh the cache

Links not updating

If links aren't being updated:

• Ensure the files aren't read-only
• Check the console (Cmd/Ctrl+Shift+I) for errors
• Try reloading Obsidian

Performance issues

If the plugin is slow:

• The initial scan of a large vault may take a few seconds
• Subsequent operations use caching and should be fast
• Check the console for any errors

Development

Project Structure

obsidian-link-updater/
├── src/
│   ├── main.ts                    # Plugin entry point
│   ├── components/
│   │   ├── DanglingLinkModal.ts   # First modal: select dangling link
│   │   └── TargetFileModal.ts     # Second modal: select target file
│   ├── services/
│   │   ├── LinkCollector.ts       # Finds dangling links
│   │   ├── LinkUpdater.ts         # Updates wikilinks
│   │   └── VaultCache.ts          # Caching layer
│   └── utils/
│       ├── LinkParser.ts          # Wikilink parsing utilities
│       └── types.ts               # TypeScript type definitions
├── manifest.json                   # Plugin manifest
├── package.json                    # NPM configuration
└── README.md                       # This file

Building

# Install dependencies
npm install

# Development build (watches for changes)
npm run dev

# Production build
npm run build

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

Roadmap

Future enhancements being considered:

• Support for markdown links [text](link.md)
• Batch operations (update multiple dangling links at once)
• Preview changes before applying
• Settings panel (exclude folders, etc.)
• Undo functionality (beyond Obsidian's built-in undo)
• Statistics dashboard

License

MIT License - see LICENSE file for details.

Credits

Created by Felix Scherz

Inspired by the workflow challenges of maintaining a large Obsidian vault with many interconnected notes.

Support

If you encounter issues or have feature requests:

• Open an issue on GitHub
• Check existing issues first to avoid duplicates

If you find this plugin useful, consider:

• Starring the repository on GitHub
• Sharing it with other Obsidian users
• Contributing improvements

---

Happy note-taking!