Link Checker

On this page

A post-build integration that checks every internal link and image reference in your Astro site for broken destinations. De-duplicates check targets so each unique destination is verified exactly once, even if it is linked from hundreds of pages.

Current version: 1.0.0 --npm

Installation

$ npm install astro-better-link-checker

Setup

In astro.config.ts:

import linkChecker from 'astro-better-link-checker';

export default defineConfig({
  integrations: [
    linkChecker(),
  ],
});

Options

Option	Type	Default	Description
`failOnBrokenLinks`	`boolean`	`true`	Throw a build error when broken links are found
`excludeSourcePages`	`(string\|RegExp)[]`	`[]`	Skip pages whose URL path matches
`excludeDestinations`	`(string\|RegExp)[]`	`[]`	Skip destinations whose path matches

What it checks

href attributes on <a> elements
src attributes on <img> elements
srcset attributes on <source> and <img> elements
Anchor fragments (/page#section) against id attributes on the target page

External links (http:// and https://) are not checked.

Algorithm

Walk the build output directory and collect all .html files
Read all files concurrently; extract links, images, and id attributes
Build a deduplicated set of unique destinations
Check all unique paths with fs.access
Validate anchor fragments against the id cache
Report broken links grouped by destination

Excluding redirects

Use excludeDestinations to skip known redirect targets that do not exist as files:

linkChecker({
  excludeDestinations: ['/old-path', /\/legacy\//],
})

Output

On a clean build, the checker prints a summary count. If broken links are found, it prints each one with the source pages that reference it:

[link-checker] /docs/missing-page
  referenced by: /docs/index.html, /docs/other.html