Navigate Markdown links like code. Ctrl+Click any link in your .md/.mdx files to jump straight to the file it points to — no more guessing which file a permalink resolves to.

Built for Astro-based documentation projects, where links are written as content URLs (e.g. /en/documentation/products/guides/cache-settings/) rather than relative file paths, making it hard to know which file a link actually opens.

Requirements

An Astro project (detected via astro.config.* or astro in package.json)
Markdown/MDX files with permalink or slug in frontmatter

Features

Go to Definition

Ctrl+Click (or press F12) on any link to jump directly to the file it resolves to. Works with Markdown links, reference-style links, JSX href/link attributes, and autolinks.

Hover Preview

Hover over a link to see the resolved file path, the confidence of the match, and a preview of the target file's content — all without leaving your document.

Peek Definition

Press Alt+F12 to preview the linked file inline, right where you're reading.

Real-time Diagnostics

Broken links are underlined as you type, and listed in the Problems panel — so dead links get caught before they ship.

Quick Fix Suggestions

When a link is broken, click the lightbulb (or press Ctrl+. / Cmd+.) for suggested fixes, ranked by similarity to existing content.

CodeLens Annotations

Every link shows its resolved destination inline, right above it — or a warning if it can't be resolved.

Autocomplete

Start typing a URL inside a link, JSX attribute, or frontmatter field, and get autocomplete suggestions from all known permalinks in your project — typos included.

Redirect Validation

If your project uses a redirects file, the extension validates entries automatically: flags redirects pointing to broken destinations, duplicate sources, and unnecessary redirects to content that already exists at that URL.

Reports

Generate HTML reports for broken links, permalink usage, and redirect health — handy for a documentation audit or cleanup pass.

Monorepo Support

Automatically detects multiple Astro projects in a single workspace (pnpm, Lerna, Nx, Turborepo) and resolves links across all of them.

Astro CMS JSON Content Links (Beta)

Validates links and images inside Astro CMS-style JSON content files (schema-driven page structs) — including href/src attributes embedded in rich-text string values — with the same CodeLens, hover, and diagnostics support as Markdown links. Files are recognized either by a _schema marker key or, for simpler pages that omit one, by having namespace/permalink present (configurable via jsonContent.requiredKeys).

Getting Started

Install the extension, then open any Markdown file in an Astro project. The status bar shows indexing progress and switches to Ready once links are resolvable. From there, Ctrl+Click any link to try it out.

All commands are available from the Command Palette under the MDLR prefix — including MDLR: List Links, MDLR: Validate Links, and the report commands.

Configuration

Most projects work out of the box with zero configuration — content roots, asset directories, and languages are auto-detected from your Astro config.

Common settings you may want to adjust, under markdownLinkResolver.*:

permalinkKeys — frontmatter keys used for link resolution (default: ["permalink"])
checkExternalUrls — enable/disable checking of external http(s) links (default: true)
externalProjectMappings — classify external URLs (e.g. a separate blog or docs site) so they're treated as external rather than broken links
projectRoots — override auto-detected project paths in a monorepo

See the full settings list in VS Code's Settings UI by searching for Markdown Link Resolver.

Support

Found a bug or have a feature request? Open an issue on the GitHub repository.

Markdown Link Resolver