Resolve links

Rewrites internal link targets using the content source map so links survive the build.

ResolveLinksPlugin normalises internal Markdown links ([text](./page.mdx), [text](../other/page)) using the content source map built at startup. It is opt-in — see Config below to enable it.

What it does

During the mdast phase, before any HTML is produced, the plugin walks every Link node. For each relative link:

1. Resolves the path relative to the current source file.

2. Looks up the resolved path in the content source map.

3. If found, rewrites the url to the final output URL for that entry.

4. If not found, emits a warning diagnostic and leaves the link unchanged.

This ensures that link targets written as relative file paths (the natural way to cross-link content while editing locally) produce correct output URLs in the built site, regardless of how the file-to-URL mapping is configured.

Config

Link resolution does nothing unless you opt in with resolveMarkdownLinks: { enabled: true } in zfb.config.ts:

export default defineConfig({
  resolveMarkdownLinks: {
    enabled: true,
    docsDir: "src/content/docs",
  },
});

For a project with more than one docs collection (e.g. EN + JA), use dirs so each collection maps to its own route prefix:

export default defineConfig({
  resolveMarkdownLinks: {
    enabled: true,
    dirs: [
      { dir: "src/content/docs", routePrefix: "/docs/" },
      { dir: "src/content/docs-ja", routePrefix: "/ja/docs/" },
    ],
  },
});

See also

• Link validation — opt-in plugin that treats broken internal links as hard build errors.

• External links — companion Core plugin for outbound links.