MD Links

Makes it easier to work with links in your Markdown files.

Add links in a couple of keystrokes, and never let a link break when you move or rename a file

  You move  src/file.cs  →  src/lib/file.cs

- [guide](../src/file.cs)        ← now broken
+ [guide](../src/lib/file.cs)    ← fixed automatically

Only the link target changes. Your formatting, link text, titles, #fragments, ?queries, and :line numbers are all preserved exactly.

Insert a link — Alt+M Alt+L

Hold Alt and press M then L (think Markdown Link), search for any file in your workspace, and a correctly-computed link is dropped at the cursor. Images become ![](…) automatically, and selected text becomes the link label.

Fix broken links when you move a file

Move or rename a file in the Explorer and MD Links offers to find every Markdown link that pointed to it and update it to the new location — no manual find & replace.

Moving the Markdown file? Its own links get fixed too

When you move the document itself, its relative links would normally all break. MD Links repairs them so they keep pointing at the right targets from the new location.

Warns you before a delete breaks links

Delete a file and MD Links checks whether any Markdown still points to it. Since a deleted file can't be auto-fixed, it shows you exactly which links will break so you can decide what to do.

Picks the right file when names clash

If a moved file's name matches more than one candidate, MD Links asks instead of guessing — you choose the correct target from a quick pick.

See every change before it's applied

Repairing the whole workspace never edits files behind your back. Right-click a folder → Repair broken references in workspace (or run it from the Command Palette) and MD Links shows the full list of proposed fixes in the Output panel, then asks Apply changes before writing anything.

Commands

| Command | What it does | |---|---| | MD Links: Repair broken references in workspace | Scan every Markdown file, preview the fixes, and apply them once you confirm. | | MD Links: Repair broken references in current file | Only scan the Markdown file you currently have open. | | MD Links: Insert link to file… | Search for a workspace file and insert a relative Markdown link at the cursor (Alt+M Alt+L). |

Settings

| Setting | Default | Description | |---|---|---| | fixRefs.autoFixOnRename | true | When a file is moved or renamed, offer to fix Markdown references to its old path. | | fixRefs.warnOnDelete | true | When a file is deleted, warn if any Markdown links still point to it. | | fixRefs.exclude | [] | Extra glob patterns to ignore when scanning. | | fixRefs.insertLinkStyle | relative | Whether Insert link to file writes a relative (portable) or absolute (full) path. |

The Alt+M Alt+L shortcut is fully rebindable in Keyboard Shortcuts (Ctrl+K Ctrl+S → search "MD Links: Insert link to file").

How it works

The extension is a thin VS Code shell over the fix-refs library, which parses Markdown into an AST and rewrites only the URL token of broken links. Everything else in the document stays byte-for-byte unchanged.

On top of the library, the extension also listens for VS Code's file rename/move events, so it can catch files that were renamed (not just moved). The rename mapping is passed straight to the fixer, which lets it repair references that a path-based search alone couldn't detect.

Requirements

• VS Code 1.75 or later
• Node.js 18 or later (bundled with VS Code on most platforms)