# Link Checker

Fast intra-site broken link and image checker that deduplicates destinations.

> For the index of this section of the site, see [llms.txt](https://better-static-sites.github.io/llms.txt)

# Link Checker

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](https://www.npmjs.com/package/astro-better-link-checker)

## Installation

```shell-session
$ npm install astro-better-link-checker
```

## Setup

In `astro.config.ts`:

```typescript
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

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

Excluding redirects

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

```typescript
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:

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