Resolve Links

Rewrites relative .mdx/.md links to clean doc URLs using the content source map.

Core feature — always active, no configuration required.

What it does

When you write a relative link in markdown using a file path — such as [link](./other-page.mdx) — zfb rewrites that path to the final URL the page will be served at. This lets you author links as file-relative paths while the built site serves clean URLs with no .mdx extension.

The rewriting process during the mdast phase:

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

2. Looks up the resolved path in the content source map built at startup.

3. Replaces the link target with the mapped output URL.

4. Emits a warning if the target file does not exist in the source map.

Example

See [configuration options](./resolve-links.mdx) for details.

Outputs a link pointing to /docs/markdown-features/resolve-links, not the raw file path.

Broken-link warnings

When the target file does not exist in the source map, zfb emits a diagnostic warning. The build does not fail on broken links by default. To escalate warnings to errors, enable the opt-in Link Validation feature.

Advanced: multiple directories, locales, and versions

Resolve Links maps each content directory to a route prefix. zfb registers one entry per directory so the rewriter knows which URL prefix corresponds to each source tree.

The default single-locale setup registers one directory:

resolveMarkdownLinks: {
  enabled: true,
  dirs: [
    { dir: settings.docsDir, routePrefix: "/docs/" },
  ],
}

When locales are configured, each locale's content directory gets its own entry with a locale-prefixed route:

resolveMarkdownLinks: {
  enabled: true,
  dirs: [
    { dir: settings.docsDir, routePrefix: "/docs/" },
    // Per-locale: each locale dir maps to /<code>/docs/
    { dir: settings.locales.ja.dir, routePrefix: "/ja/docs/" },
  ],
}

This is why a relative link such as [page](./other.mdx) inside a Japanese source file resolves to /ja/docs/... rather than /docs/... — the rewriter matches the file's source directory to the correct prefix.

When versioned collections are also enabled, the same pattern extends to each version's EN directory and its per-locale mirrors:

resolveMarkdownLinks: {
  enabled: true,
  dirs: [
    { dir: settings.docsDir, routePrefix: "/docs/" },
    { dir: settings.locales.ja.dir, routePrefix: "/ja/docs/" },
    // Versioned: EN dir + per-locale dirs for each version
    { dir: version.docsDir, routePrefix: "/v/1.0/docs/" },
    { dir: version.locales.ja.dir, routePrefix: "/v/1.0/ja/docs/" },
  ],
}

The actual zfb.config.ts in this project builds the dirs array dynamically from settings.locales and settings.versions, so entries are added automatically as new locales or versions are registered — no manual dirs edits are needed when you add a locale or a version.

Notes

• The plugin operates during the mdast phase, before hast processing.

• The Strip .md Extension feature runs after Resolve Links and removes any remaining .md or .mdx suffix from link hrefs in the final output.

• Absolute URLs are not touched by this plugin.