Skip to main content

Link validation

View as Markdown

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, renamed pages, and moved custom docs before they ship.

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 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 homepageLink 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. It's skipped when running in SSR mode, since pages are rendered on demand rather than generated up front.

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​

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 for how paths are matched.

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

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.