Link Validation

Installation

This plugin is included in fumapress.

Enable the plugin in your Fumapress config:

import { defineConfig } from "fumapress";
import { linkValidationPlugin } from "fumapress/plugins/link-validation";

export default defineConfig({
  // ...
})
  .plugins(linkValidationPlugin());

During static generation, the plugin collects links rendered with <Link /> component. After the build finishes pre-rendering, it validates each unique href:

• Relative links — fetched against your app. A 404 response fails the build.
• Absolute URLs — skipped unless you provide an externalLink callback.

If any link is broken, the build throws an error listing the source page and target URL:

In "/docs/getting-started": link "/docs/missing-page" not-found

Options

ignored

Skip validation for specific links:

import { linkValidationPlugin } from "fumapress/plugins/link-validation";

export default defineConfig({
  // ...
}).plugins(
  linkValidationPlugin({
    ignored(href) {
      return href.startsWith("https://example.com");
    },
  }),
);

externalLink

Validate external (absolute) URLs. Return "not-found" to fail the build, or null when the link is valid:

import { linkValidationPlugin } from "fumapress/plugins/link-validation";

export default defineConfig({
  // ...
}).plugins(
  linkValidationPlugin({
    async externalLink(href) {
      const res = await fetch(href, { method: "HEAD" });
      return res.ok ? null : "not-found";
    },
  }),
);

report

By default a broken link fails the build. To report problems as data instead — so a CI check can annotate a pull request rather than parse an error message — switch report:

import { linkValidationPlugin } from "fumapress/plugins/link-validation";

export default defineConfig({
  // ...
}).plugins(
  linkValidationPlugin({
    report: "json",
  }),
);

The file is written to the build output directory, next to public and server:

{
  "diagnostics": [
    {
      "severity": "error",
      "rule": "link-validation/not-found",
      "message": "link \"/missing\" not-found",
      "fromPathname": "/docs",
      "href": "/missing"
    }
  ]
}

It is written on every build, including when nothing is wrong, so an empty diagnostics array means validation ran and found no problems rather than that it never ran.

diagnosticsPath

Change the file name, relative to the build output directory. Defaults to fumapress-diagnostics.json.