Better Markdown Links

[[Wikilinks]] are not part of the Markdown spec, so a vault that uses them stops making sense outside Obsidian. Switch to Markdown links and you hit the next problem: Obsidian writes [Title](path%20with%20space/note%20with%20space.md), which is unreadable, and it writes relative paths without a leading ./, which other editors resolve differently than Obsidian does — the same link, two meanings.

This plugin makes Obsidian generate the readable, unambiguous form instead: angle brackets around paths with spaces, an explicit ./ on relative links, and tidy file:// URLs. It can also convert the links you already have, in one note, one folder, or the whole vault — and decide for itself which style and which path form to write, rather than following Obsidian's own settings.

More screenshots

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 awkward paths already in place to try it against.

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 Better Markdown Links: Open demo vault command.
2. Downloading better-markdown-links-demo-vault.zip from the Releases. It unzips into a single better-markdown-links-demo-vault-<version> folder.
3. Browsing its source in demo-vault/ in this repository.

What it does

• Angle bracket links — [Title](<path with space/note.md>) instead of %20 noise: 01 Angle bracket links.
• Explicit relative links — a leading ./, so a relative path cannot be mistaken for an absolute one: 02 Relative links.
• The [[ autocomplete too — a link picked from it is written in the configured form as it is inserted, not rewritten afterwards: 01 Angle bracket links.
• Convert what you already have — a selection, a note, a folder or the whole vault, on command or automatically as you save: 03 Convert links.
• file:// normalization — escaped backslashes in a file:// link become plain forward slashes: 03 Convert links.
• Force Markdown links — whatever Obsidian's Use [[Wikilinks]] setting says, permanently or for one run: 03 Convert links.
• Force a link path style — relative, shortest or vault-absolute, whatever Obsidian's New link format setting says: 03 Convert links.
• Demote embeds to links — strip the ! off every embed in a selection, a note, a folder or the vault: 04 Demote embeds.
• Links that do not resolve — point an alias-only wikilink at the note carrying the alias, or create the note: 03 Convert links.
• Undo a folder or vault run with git — in a vault kept in git, each in-folder or entire-vault run becomes one commit that the Undo a bulk operation... command reverts: 05 Settings.
• Strict link resolution — resolve a link only relative to its note or as a vault path, never to a same-named note in another folder: 02 Relative links.
• GitHub heading anchors — follow [x](note.md#my-heading) the way GitHub does, and optionally write heading links that way too: 06 GitHub heading anchors.
• Leave chosen links alone — keep links to matching targets, such as ![[file.base]] embeds, exactly as written while converting the rest: 03 Convert links.

Integration with other plugins

• Since 5.0.0, renames and deletes are handled by Advanced Rename and Delete Handler, which this plugin offers to install: 05 Settings.
• Backlink Cache speeds this plugin up on a large vault.
• Advanced Metadata Cache, with its Names module on, speeds up resolving links via aliases: 03 Convert links.

See also

My other Obsidian resources

Last searched for similar plugins on 2026-10-26.

For plugin developers

This plugin publishes an API, generateMarkdownLinkExtended(), through the @mnaoumov/obsidian-lib plugin registry under the id better-markdown-links, for a plugin that wants to write the same links without re-implementing them. Copy api.d.ts and api-contract.ts into your plugin.

Usage, the contract, versioning, and moving over from the pre-6.0.0 generateMarkdownLink.extended(): Plugin API.

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:

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 (id: better-markdown-links) 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 Better Markdown Links: 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.

License

© Michael Naumov