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.
Opt-in feature — enabled in warn mode
This feature is enabled in zudo-doc's zfb.config.ts as linkValidation: { failOnBroken: false } — warn mode. It is an object-typed feature, so it must be given an options object. In warn mode it never fails the build; broken references are reported as build diagnostics only.
Configuration
Enable with defaults (warn-only, external URLs skipped):
export default defineConfig({
markdown: {
features: {
linkValidation: {},
},
},
});zudo-doc sets failOnBroken: false explicitly to make the warn-only intent clear:
linkValidation: { failOnBroken: false },To fail the build on broken links instead (not used in zudo-doc — it would break CI):
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 (
.) — the target file must exist./ other. md File links with anchors (
.) — both the file and the heading ID must resolve. As of zfb/ other. md# section- id 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.