Markdown Link Resolver

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, at the workspace root or nested in a monorepo). In any other workspace the extension stays inactive: no status bar item, no commands in the Command Palette, and a single line in the Markdown Link Resolver output channel explaining why.
• Markdown/MDX files with a permalink in frontmatter (other keys, such as slug, can be added via permalinkKeys)

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 file it resolves to, the URL Astro publishes it at, a preview of the target (or the image itself), and the other files that link to the same page — all without leaving your document. Links that go through a redirect show every hop of the chain.

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.

Open Page in Localhost

Right-click a content file — or click the Open Page in Localhost lens at the top of it — to open that page in your browser on the local dev server. The extension takes the file's permalink, builds the exact URL Astro publishes it at, and opens it. Collection-routed pages are handled too: a blog post whose published URL adds segments the raw permalink doesn't contain (e.g. /en/blog/{permalink}/) is resolved from the real Astro page route, so you still land on the right page.

The dev server address is worked out for you: no configuration is needed if you just run pnpm dev. Since Astro picks 4321 and counts up when that port is taken, the extension asks each candidate port for the page itself and opens the server that actually serves it — so with two projects running at once, you still land on the right one. Set devServerUrl if you run somewhere unusual.

The entry appears for any file that maps to a permalink, whatever its format — Markdown, MDX, or JSON content pages — and stays hidden on files that don't.

Redirect Validation

Redirects are opt-in. Set "markdownLinkResolver.redirects.mode": "full" to enable redirect resolution and redirect JSON validation. The default ("off") skips the workspace JSON scan entirely, and markdown links that only resolved through a redirect will show up as broken until you opt in. The current mode is always shown in the status bar item's tooltip, so if redirects seem to have vanished, that's the first place to check.

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. When redirect files are found in a workspace with redirects still off, a one-time notification offers to turn them on — closing that notification without choosing doesn't count as "no", so it may ask again later; only explicitly dismissing it ("Don't show again") stops it for good.

A redirect JSON file only gets this treatment once the extension's file watcher has discovered it — a brand-new or not-yet-saved redirect file gets no diagnostics, CodeLens, hover, or resolution until it's picked up.

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"])
• devServerUrl — dev server base URL for Open Page in Localhost, as a full URL or a bare port (default: "", i.e. detect automatically)
• openInDev.showCodeLens — show the Open Page in Localhost lens at the top of files with a permalink (default: true)
• redirects.mode — how much of the redirect system is active: off | linksOnly | full (default: "off"; see Redirect Validation)
• 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.

License

Proprietary - all rights reserved. See LICENSE.