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.

:::note[Included in the standard preset — warn mode]

`zudoDoc()` enables Link Validation as `linkValidation: { failOnBroken: false }` — **warn mode**. No separate configuration field is necessary for this default. In warn mode it never fails the build; broken references are reported as build diagnostics only.

:::

## Configuration

No configuration is required to get this default:

```ts title="zfb.config.ts"
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:

```ts title="zfb.config.ts"
const base = zudoDoc({
  // ...your project settings
});

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

## Options

| Option | Default | Description |
| --- | --- | --- |
| `failOnBroken` | `false` | When `true`, broken links produce `Error` diagnostics and fail the build. When `false`, they are warnings only. |

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.