# Link validation

Copy as Markdown[View as Markdown](/docs/development/deployment/link-validation.md)

***

After a static build, EventCatalog scans every generated HTML page and reports internal links and anchors that don't resolve. This catches typos in [resource references](/docs/development/components/resource-references.md), renamed pages, and moved custom docs before they ship.

## What gets checked[​](#what-gets-checked "Direct link to What gets checked")

* Links between pages rendered by your catalog, including the sidebar navigation.
* Anchors (`#section`) on the destination page, so a link to a heading that no longer exists is caught too.
* Links are resolved against your [`base`](/docs/api/config.md#base) path, so this works the same whether your catalog is hosted at the root or a subpath.

Only links on the same origin and under the catalog's `base` path are checked. Set [`site`](/docs/api/config.md#site) to your deployed URL so absolute links to your own catalog are recognized as internal. External links and non-HTTP links such as `mailto:` are skipped.

Links to files in the build output are checked for existence, but fragments in non-HTML files such as PDFs are not validated. Links created only by client-side JavaScript are not checked, except for sidebar navigation.

info

Link validation only runs after a [static build](/docs/development/deployment/build-and-deploy.md). It's skipped when running in [SSR mode](/docs/development/deployment/build-ssr-mode.md), since pages are rendered on demand rather than generated up front.

## Configure the check[​](#configure-the-check "Direct link to Configure the check")

By default, broken links and anchors are logged as warnings and the build still succeeds.

eventcatalog.config.js

```
module.exports = {
  linkValidation: {
    onBrokenLinks: 'warn',
    onBrokenAnchors: 'warn',
  },
};
```

Set either option to `error` to fail the build instead, or `ignore` to skip that check completely.

eventcatalog.config.js

```
module.exports = {
  linkValidation: {
    onBrokenLinks: 'error',
    onBrokenAnchors: 'ignore',
  },
};
```

Turn the whole feature off by setting `linkValidation` to `false`.

eventcatalog.config.js

```
module.exports = {
  linkValidation: false,
};
```

## Ignore known destinations[​](#ignore-known-destinations "Direct link to Ignore known destinations")

Some links can't be verified during the build, such as pages generated by a separate process. Use `ignore` with glob patterns for the destination paths. See [`linkValidation.ignore`](/docs/api/config.md#linkvalidationignore) for how paths are matched.

eventcatalog.config.js

```
module.exports = {
  linkValidation: {
    ignore: ['/api/**', '/docs/legacy/*'],
  },
};
```

## Run in CI[​](#run-in-ci "Direct link to Run in CI")

Set both checks to `error` in CI to fail the build on broken links or anchors. Keep `warn` locally if you want the build to succeed while you fix them.

eventcatalog.config.js

```
module.exports = {
  linkValidation: {
    onBrokenLinks: process.env.CI ? 'error' : 'warn',
    onBrokenAnchors: process.env.CI ? 'error' : 'warn',
  },
};
```

.github/workflows/build-catalog.yml

```
name: Build catalog
on:
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm install
      - run: npm run build
        env:
          CI: true
```

When a check is set to `error`, broken destinations fail the build. Diagnostics group references by destination and show up to five source pages per destination. For user/team and event/command/query mixups, EventCatalog suggests an alternative only when that destination exists in the build.

## Related[​](#related "Direct link to Related")

* [`eventcatalog.config.js` reference](/docs/api/config.md#linkValidation) for the full list of options
* [Resource references](/docs/development/components/resource-references.md) for linking to catalog resources