Link Validation

Validates internal links at build time and warns (or errors) on broken references.

The linkValidation feature checks internal links and anchor fragments during the build to catch broken references before deployment. It inspects <a href> and <img src> elements, verifying that internal links and anchor fragments resolve correctly.

Configuration

No configuration is required to get this default:

import { defineConfig } from "zfb/config";
import { zudoDoc } from "@takazudo/zudo-doc/config";

export default defineConfig(
  zudoDoc({
    siteName: "My Docs",
  }),
);

To fail the build on broken links instead (not used in zudo-doc — it would break CI), spread the preset's markdown.features and override linkValidation — a bare defineConfig({ markdown: { features } }) would discard the rest of the preset:

const base = zudoDoc({
  // ...your project settings
});

export default defineConfig({
  ...base,
  markdown: {
    ...base.markdown,
    features: {
      ...base.markdown.features,
      linkValidation: { failOnBroken: true },
    },
  },
});

Options

An allowExternal option existed in earlier zfb releases but never had any effect; it was removed in zfb 0.1.0-next.38. Remove it from your config if present.

What gets validated

• Bare anchor fragments (#section-id) against heading IDs in the current file.

• File links without anchors (./other.md) — the target file must exist.

• File links with anchors (./other.md#section-id) — both the file and the heading ID must resolve. As of zfb 0.1.0-next.38, the anchor is checked against the target file's actual headings (including transcluded ones), not just file existence; targets outside the bundler's walked directories degrade to existence-only validation.

External URLs (http://, https://, mailto:, tel:) are always skipped.

Relationship to resolveMarkdownLinks

zudo-doc already runs zfb's resolveMarkdownLinks with onBrokenLinks: "warn", which resolves relative .mdx/.md links to clean route URLs and warns on broken file links. On this corpus, linkValidation in warn mode emits no distinguishable output beyond that — broken file links surface through resolveMarkdownLinks, and neither configuration fails the build. The two are complementary build-time link checks, both kept in warn mode so a stray broken reference does not block a deploy.