@eventcatalog/core 4.10.13 → 4.10.15

package/dist/docs/development/components/diagram-syntax/06-mermaid.md

@@ -29,7 +29,7 @@ If you have large diagrams that fail to render, increase the `maxTextSize` confi
 
 ### Using the `mermaid` code block in any markdown file.
 
-To use mermaid you need to use the `mermaid` code block in any markdown file.
+To use mermaid you need to use the `mermaid` code block in any markdown file. You can pass `placement` and `actions` on the code fence to configure the [interactive controls](#control-options).
 
 #### Example
 
@@ -74,6 +74,9 @@ Add your .mmd or .mermaid file to your folder (e.g `/events/MyEvent/mermaid.mmd`
 
 <!-- Using the .mermaid file extension -->
 <MermaidFileLoader file="my-second-mermaid-file.mermaid" />
+
+<!-- Optional: configure interactive controls -->
+<MermaidFileLoader file="mermaid.mmd" placement="top-left" actions={false} />
 ```
 
 This example will load a mermaid file (.mmd or .mermaid) into your EventCatalog page.
@@ -180,22 +183,58 @@ All Mermaid diagrams include interactive controls for better viewing and explora
 
 ![Example output of mermaid](../img/interactive.png)
 
+Pan, zoom, reset, fullscreen, and copy controls appear on hover. On touch devices the controls stay visible.
+
 ### Zoom and pan
 
-Click and drag to pan around the diagram, or use the zoom controls in the bottom-left corner to zoom in and out. Double-click the diagram to zoom in quickly.
+Click and drag to pan around the diagram, or use the pan and zoom buttons to move around. Double-click the diagram to zoom in quickly. Use reset to fit the diagram back into view.
 
-### Presentation mode
+### Fullscreen
 
-Click the presentation button in the top-left corner to view the diagram in fullscreen. In presentation mode, mouse wheel zooming is enabled for precise control.
+Click the fullscreen button to open the diagram in a modal. In fullscreen you can drag, scroll, or pinch to zoom.
 
-Press `Escape` to exit presentation mode.
+Keyboard shortcuts in fullscreen:
+- Arrow keys to pan
+- `+` / `-` to zoom
+- `0` to reset
+- `Escape` to close
 
 ### Copy diagram code
 
-Click the copy button in the top-right corner to copy the diagram code to your clipboard. 
+Click the copy button to copy the diagram code to your clipboard.
 
 Useful for copying diagrams into LLM prompts.
 
+### Control options
+
+<AddedIn version="4.10.6" />
+
+Code blocks and [`<MermaidFileLoader />`](/docs/development/components/components/mermaid-file-loader) accept `placement` and `actions` to configure the controls.
+
+| Name | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| `placement` (optional) | `'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right'` | `'top-right'` | Corner for the interactive controls. |
+| `actions` (optional) | `boolean` | shown when the diagram is taller than 120px | `true` always shows the controls. `false` hides them. |
+
+#### Code block
+
+Pass the options on the `mermaid` code fence. `placement` accepts double or single quotes. `actions` accepts `{true}` / `{false}` or `true` / `false`.
+
+```markdown
+```mermaid placement="top-left" actions={false}
+sequenceDiagram
+    participant Customer
+    participant OrdersService
+    Customer->>OrdersService: Place Order
+```_
+```
+
+#### MermaidFileLoader
+
+```md
+<MermaidFileLoader file="mermaid.mmd" placement="top-left" actions={false} />
+```
+
 ## Export NodeGraphs as Mermaid
 
 <AddedIn version="3.9.0" />

package/dist/docs/development/customization/04-documentation-sidebar.md

@@ -9,7 +9,7 @@ description: Pick and customize the documentation sidebar.
 
 import AddedIn from '@site/src/components/MDX/AddedIn';
 
-The documentation sidebar is a [context aware sidebar](#what-is-context-aware-sidebar) that is shown on the `/docs/` pages.
+The documentation sidebar is a [context aware sidebar](#what-is-a-context-aware-sidebar) that is shown on the `/docs/` pages.
 
 Clicking on any resource in the sidebar will show you related information to that selected resource ([see demo](https://demo.eventcatalog.dev/)).
 
@@ -56,9 +56,9 @@ You can specify the following options in the `navigation.pages` property:
 
 - [Top level options](#top-level-options) 
   - Useful if you want to show the top-level resources in your catalog in the sidebar. For example high level domains and let your users drill down.
-- [List all resources (by type)](#list-all-resources-type)
+- [List all resources (by type)](#list-all-resources-by-type)
   - Useful if you want to show all resources of a specific type in the sidebar. For example all domains, services, messages, etc.
-- [Pick specific resources to show](#pick-specific-resources-to-show)
+- [Pick specific resources to show](#chose-which-resources-to-show)
   - Useful if you want to show a specific resource or a group of resources in the sidebar. For example a specific domain, service, message, etc.
 - [Custom groups and links](#custom-groups-and-links)
   - Useful if you want to create custom groups and links to external pages in the sidebar. For example a group of resources, or a link to an external page.

package/dist/docs/development/customization/05-resource-sidebar.md

@@ -0,0 +1,235 @@
+---
+sidebar_position: 2.5
+keywords:
+- EventCatalog resource sidebar
+- customize sidebar
+- sidebar.json
+sidebar_label: Resource sidebar
+title: Resource sidebar
+description: Define your own sidebar for any resource with a sidebar.json file.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="4.10.0" />
+
+Every resource in EventCatalog (domains, services, messages, flows, and more) gets a generated sidebar showing its quick reference, architecture, related resources and owners.
+
+![The resource sidebar shown on a system page](./img/resource-sidebar.png)
+
+By default, EventCatalog will generate a sidebar for your resources, but sometimes you may want to customize what is shown here — for example runbooks, guides, external links, or your own grouping of events and services.
+
+To do this, add a `sidebar.json` file next to the resource's `index.mdx`. This file becomes the sidebar for that resource.
+
+```
+domains/
+  Payments/
+    index.mdx
+    sidebar.json        <-- your sidebar for the Payments domain
+```
+
+:::info The file is the sidebar
+When a `sidebar.json` is present it fully replaces the generated sidebar — what you list is what renders, in the order you list it. Nothing is merged in, and anything you don't list isn't shown. Remove the file to get the default sidebar back.
+:::
+
+## Which resources support it?
+
+All of them. A `sidebar.json` can sit next to the `index.mdx` of any **domain, system, service, agent, event, command, query, flow, container (data store), entity, data product or ADR**.
+
+Versioned copies (`versioned/0.0.1/index.mdx`) inherit the resource folder's `sidebar.json` automatically, unless the versioned folder contains its own.
+
+## Quick start
+
+A sidebar is a list of **sections**. A section is either a predefined `$token` (a section EventCatalog generates and keeps up to date for you) or a group you define yourself:
+
+```json title="domains/Payments/sidebar.json"
+{
+  "sections": [
+    // A predefined section, relabelled from "Quick Reference" to "Overview"
+    { "section": "$quick-reference", "title": "Overview" },
+    // Your own group — any Lucide icon name works
+    {
+      "title": "Runbooks",
+      "icon": "Siren",
+      "pages": [
+        // Links to this domain's runbooks/failed-captures documentation page
+        "[[doc|runbooks/failed-captures]]",
+        // A plain link — external links open in a new tab
+        { "title": "Health dashboard", "href": "https://grafana.acme.dev/d/payments" }
+      ]
+    },
+    // Predefined sections, rendered exactly as the default sidebar would
+    "$architecture",
+    "$services",
+    "$owners"
+  ]
+}
+```
+
+This renders: an **Overview** section (the generated Quick Reference, relabelled), your own **Runbooks** group, then the generated **Architecture**, **Services** and **Owners** sections.
+
+## Sections
+
+Each entry in `sections` is one of three shapes:
+
+| Shape | Example | Meaning |
+|-------|---------|---------|
+| Token | `"$architecture"` | A predefined section, rendered exactly as the default sidebar would — and kept up to date as your catalog changes |
+| Adjusted token | `{ "section": "$owners", "title": "Team" }` | A predefined section with a new `title`, `icon` or `collapsed` state |
+| Custom group | `{ "title": "Runbooks", "icon": "Siren", "pages": [...] }` | A group you define. `icon` is any [Lucide](https://lucide.dev) icon name |
+
+A predefined section with nothing behind it (for example `$entities` on a domain with no entities) renders nothing — you can safely list sections that only sometimes have content.
+
+## Pages
+
+Inside a custom group, each entry in `pages` is one of:
+
+| Entry | Example | Renders |
+|-------|---------|---------|
+| Section token | `"$inbound-messages"` | The **items** of a predefined section, spliced into your group — this is how you extend a generated section with your own pages |
+| Resource reference | `"[[service\|payment-api]]"` | The resource, with its own expandable nested sidebar, at its latest version. Messages can pin a version: `"[[event\|payment-captured@1.0.0]]"` — other types always reference the latest |
+| Documentation reference | `"[[doc\|guides/onboarding]]"` | One of this resource's [documentation pages](/docs/development/bring-your-own-documentation/resource-docs/adding-resource-docs), addressed as `<type>/<id>` |
+| Specification reference | `"[[spec\|openapi.yml]]"` | A specification page, with the OpenAPI/AsyncAPI/GraphQL logo and the spec's name |
+| Schema reference | `"[[schema\|payment-captured]]"` | A message's schema page |
+| Link | `{ "title": "Runbook", "href": "https://..." }` | A plain link. External links (any protocol) open in a new tab and show an external-link icon |
+| Nested group | `{ "title": "Internal", "collapsed": true, "pages": [...] }` | A subsection. Groups nest to any depth |
+
+Resource references accept any resource type: `domain`, `system`, `service`, `agent`, `event`, `command`, `query`, `flow`, `container`, `entity`, `channel`, `data-product`, `adr`, `diagram`, `team`, `user`.
+
+### Specification and schema references
+
+Specifications belong to a resource, so a spec reference names the file — and optionally the resource that owns it:
+
+```json
+"[[spec|openapi.yml]]"                              // this resource's own spec
+"[[spec|payment-api/openapi.yml]]"                  // another resource's spec, by id
+"[[spec|service/payment-api/openapi.yml]]"          // type-qualified
+```
+
+Specifications always come from the owner's latest version.
+
+Schema references point at a message's schema page:
+
+```json
+"[[schema|payment-captured]]"                       // latest version
+"[[schema|event/payment-captured@1.0.0]]"           // type-qualified and pinned to a version
+```
+
+### Extending a generated section
+
+Because a `$token` inside `pages` splices in that section's items, extending a generated section is just wrapping it in your own group — placement is list order:
+
+```json
+{
+  "title": "Quick Reference",
+  "icon": "BookOpen",
+  "pages": [
+    // Splices in the generated Quick Reference items (Overview, Changelog, ...)
+    "$quick-reference",
+    // ...followed by your own pages
+    "[[doc|guides/onboarding]]",
+    { "title": "Team Slack", "href": "https://acme.slack.com/archives/payments" }
+  ]
+}
+```
+
+### Link placeholders
+
+Internal links can use `{collection}`, `{id}` and `{version}` placeholders for the resource the sidebar belongs to, so the same file works across versions:
+
+```json
+// On the Payments domain v1.0.0 this renders as
+// "Visualiser (1.0.0)" -> /visualiser/domains/payments/1.0.0
+{ "title": "Visualiser ({version})", "href": "/visualiser/{collection}/{id}/{version}" }
+```
+
+Internal links automatically respect your configured base path.
+
+## Collapsing sections
+
+Any object-form section or group accepts `"collapsed": true | false` as its **initial** state — users can still toggle it, and their choice is remembered:
+
+```json
+// Starts collapsed; users can still expand it and their choice is remembered
+{ "title": "Internal commands", "collapsed": true, "pages": ["[[command|refund-payment]]"] }
+```
+
+Without `collapsed`, groups with more than five items start collapsed and smaller groups start open.
+
+## Predefined sections
+
+Tokens shared by most resource types:
+
+`$quick-reference` · `$documentation` · `$architecture` · `$diagrams` · `$decision-records` · `$owners` · `$code` · `$attachments`
+
+And per resource type:
+
+| Resource | Tokens |
+|----------|--------|
+| Domain | `$api-and-contracts` `$systems` `$subdomains` `$resources` `$services` `$flows` `$entities` `$domain-events` `$external-events` `$resource-groups` `$agents` `$external-integrations` `$data-products` |
+| System | `$resources` `$services` `$flows` `$data-stores` `$entities` |
+| Service / Agent | `$api-and-contracts`* `$resource-groups` `$state-and-persistence` `$entities`* `$outbound-messages` `$inbound-messages` `$channels` `$flows` |
+| Event / Command / Query | `$api-and-contracts` `$producers` `$consumers` `$triggered-by` `$triggers` `$appears-in-flows` |
+| Flow | `$messages` `$services` `$agents` `$subflows` `$data-stores` `$data-products` |
+| Container | `$writes` `$reads` `$appears-in-flows` |
+| Data product | `$inputs` `$outputs` `$data-contracts` `$appears-in-flows` |
+| Entity | `$domains` `$services` |
+| ADR | `$applies-to` `$supersedes` `$superseded-by` `$amends` `$amended-by` `$related-decisions` `$decision-makers` |
+
+\* service only.
+
+Tokens like `$services` that the default sidebar nests inside a "Resources" umbrella render as top-level sections when you use them directly.
+
+## When something doesn't resolve
+
+Mistakes fail fast so your catalog never silently ships a broken sidebar:
+
+- An unknown `$token`, or a `[[doc|…]]`, `[[spec|…]]` or `[[schema|…]]` reference that doesn't resolve **fails the build**, with an error naming the file and listing the valid options.
+- A resource reference (like `[[service|…]]`) to something that doesn't exist renders nothing.
+
+## A complete example
+
+The [demo catalog](https://demo.eventcatalog.dev/docs/domains/catalog/1.0.0) uses resource sidebars throughout. The Catalog domain's sidebar organizes the domain for its consumers — guides first, then the events other teams integrate with:
+
+```json title="domains/Catalog/sidebar.json"
+{
+  "sections": [
+    // Generated Quick Reference, relabelled
+    { "section": "$quick-reference", "title": "Overview" },
+    // The domain's documentation pages, front and center for new consumers
+    {
+      "title": "Guides",
+      "icon": "BookOpen",
+      "pages": [
+        "[[doc|guides/integrating-with-the-catalog]]",
+        "[[doc|guides/product-data-model]]",
+        "[[doc|guides/event-versioning]]"
+      ]
+    },
+    // A curated list of the events other teams subscribe to.
+    // Each renders with its own expandable nested sidebar.
+    {
+      "title": "Integration Events",
+      "icon": "Radio",
+      "pages": ["[[event|product-created]]", "[[event|product-updated]]", "[[event|product-deleted]]"]
+    },
+    // Generated sections — kept up to date as the catalog changes
+    "$architecture",
+    "$systems",
+    "$entities",
+    // Docs mixed with external links in one group
+    {
+      "title": "Runbooks",
+      "icon": "Siren",
+      "pages": [
+        "[[doc|runbooks/on-call]]",
+        "[[doc|runbooks/search-index-lag]]",
+        { "title": "Health dashboard", "href": "https://grafana.acme.dev/d/catalog-overview" }
+      ]
+    },
+    // Out of the way until needed
+    { "title": "Decisions", "icon": "ClipboardList", "collapsed": true, "pages": ["[[adr|adr-001-use-transactional-outbox]]"] },
+    "$owners"
+  ]
+}
+```

package/dist/docs/development/customization/09-embed-eventcatalog.md

@@ -0,0 +1,179 @@
+---
+sidebar_position: 11
+sidebar_label: Embed EventCatalog
+title: Embed EventCatalog in other applications
+description: Bring EventCatalog documentation, diagrams, schemas, messages, and flows into your internal applications.
+keywords:
+  - embed EventCatalog
+  - iframe
+  - developer portal
+  - internal application
+  - Scale
+---
+
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+
+<PlanBanner plan="Scale" />
+
+You can embed EventCatalog pages in developer portals, internal tools, intranets, and other web applications. Your teams can explore architecture information in the application where they already work while EventCatalog remains the source of the documentation.
+
+Embedding EventCatalog requires an EventCatalog Scale license. See [Getting a license key for EventCatalog Scale](/docs/development/license-keys/plans).
+
+## What you can embed
+
+| Feature | What users can do in the embedded view |
+| --- | --- |
+| Resource documentation | Read the documentation for a domain, system, service, message, flow, team, or another catalog resource. |
+| Resource visualizer | Explore the selected resource and its relationships. |
+| Architecture Graph | Explore the catalog-wide graph or focus it on a resource with a relationship depth of 1, 2, or 3. |
+| System Context Maps | View the catalog-wide system overview or the context surrounding one system. |
+| Entity maps | Explore the entities and relationships associated with a resource. |
+| Flows | Follow the steps, services, and messages in a business or technical flow. |
+| Discovery tables | Browse and filter catalog resources such as services, events, commands, and queries. |
+| Schema explorer | Search schemas, inspect their contents, and see the resources that use them. |
+
+Embedded pages remain interactive. Controls belonging to the selected visualization or table stay available, while EventCatalog's application header and sidebars are removed so they do not compete with the host application's navigation.
+
+## How embedding works
+
+Add `embed=true` to a supported EventCatalog URL and load that URL in an iframe. For example:
+
+```text
+https://catalog.example.com/docs/services/order-service/1.0.0?embed=true
+```
+
+You can also request a light or dark color mode for an embed:
+
+```text
+https://catalog.example.com/docs/services/order-service/1.0.0?embed=true&theme=dark
+```
+
+The requested theme only affects that embedded page. It does not replace the visitor's saved EventCatalog theme.
+
+## Before you embed
+
+- Build and deploy EventCatalog with a valid Scale license.
+- Use an EventCatalog URL that users of the host application can reach from their browsers.
+- If EventCatalog is authenticated, verify that users can authenticate from the embedded context.
+- Give the iframe's parent a defined height. EventCatalog fills the space the host application provides.
+- Review the host application's Content Security Policy and iframe policy if the browser blocks the page.
+
+## Embed a page
+
+### 1. Choose the EventCatalog page
+
+Open the page in EventCatalog and confirm that it contains the content you want users to see. Prefer an explicit resource version so the embedded URL is stable.
+
+For example, a service visualizer may have this URL:
+
+```text
+https://catalog.example.com/visualiser/services/order-service/1.0.0
+```
+
+### 2. Enable embed mode
+
+Add `embed=true` to the query string:
+
+```text
+https://catalog.example.com/visualiser/services/order-service/1.0.0?embed=true
+```
+
+Use `&embed=true` instead when the URL already has query parameters.
+
+### 3. Add the iframe
+
+Give the container a concrete height and let the iframe fill it:
+
+```html
+<div style="height: 700px; width: 100%;">
+  <iframe
+    src="https://catalog.example.com/visualiser/services/order-service/1.0.0?embed=true"
+    title="Order service architecture"
+    loading="lazy"
+    style="border: 0; display: block; height: 100%; width: 100%;"
+  ></iframe>
+</div>
+```
+
+`height: 100%` only works when the iframe's ancestors have a defined height. Use a fixed, viewport-relative, or layout-controlled height in the host application.
+
+### 4. Select a theme
+
+Add `theme=light` or `theme=dark` to force the embedded page's color mode:
+
+```html
+<iframe
+  src="https://catalog.example.com/schemas/explorer?embed=true&theme=dark"
+  title="Schema explorer"
+></iframe>
+```
+
+If you omit `theme`, EventCatalog uses the visitor's saved EventCatalog preference or their system preference.
+
+## Embed URL reference
+
+Replace `https://catalog.example.com` with the URL of your deployed catalog.
+
+| Feature | URL pattern |
+| --- | --- |
+| Resource documentation | `/docs/{collection}/{id}/{version}?embed=true` |
+| Resource visualizer | `/visualiser/{collection}/{id}/{version}?embed=true` |
+| Discovery table | `/discover/{collection}?embed=true` |
+| Entity map | `/visualiser/{collection}/{id}/{version}/entity-map?embed=true` |
+| Data dependency view | `/visualiser/{collection}/{id}/{version}/data?embed=true` |
+| Schema explorer | `/schemas/explorer?embed=true` |
+| Schema details | `/schemas/{type}/{id}/{version}?embed=true` |
+| Architecture Graph | `/visualiser/graph?embed=true` |
+| System Context Map overview | `/visualiser/system-context-map?embed=true` |
+| System-specific context map | `/visualiser/systems/{id}/{version}/context?embed=true` |
+| Flow visualizer | `/visualiser/flows/{id}/{version}?embed=true` |
+
+Collections use their plural route names, such as `domains`, `systems`, `services`, `events`, `commands`, `queries`, `flows`, and `entities`. Schema detail pages support message types such as `events`, `commands`, and `queries`, as well as data product contracts.
+
+### Focus the Architecture Graph
+
+Use `focus={collection}/{id}` to select the initial resource and `depth` to choose how many relationship hops are visible. `depth` accepts `1`, `2`, or `3`.
+
+```text
+https://catalog.example.com/visualiser/graph?embed=true&focus=services/order-service&depth=2
+```
+
+The Architecture Graph must be enabled in `eventcatalog.config.js`:
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  visualiser: {
+    architectureGraph: {
+      enabled: true,
+    },
+  },
+};
+```
+
+## Troubleshooting
+
+### EventCatalog shows a license overlay
+
+Confirm that the deployed catalog was built or started with a valid Scale license. Add the key to the EventCatalog project's environment:
+
+```bash title=".env"
+EVENTCATALOG_SCALE_LICENSE_KEY=your-scale-license-key
+```
+
+Then rebuild and redeploy the catalog. See [Getting a license key for EventCatalog Scale](/docs/development/license-keys/plans).
+
+### Navigation is still visible
+
+Confirm that the URL contains `embed=true`, including the exact lowercase value `true`.
+
+### The iframe is blank or blocked
+
+Open the iframe URL directly in the same browser. Confirm that it is reachable and that the user can authenticate. Then check the browser console for Content Security Policy, mixed-content, or iframe permission errors from either application.
+
+### The content does not fill the available height
+
+Set an explicit height on the iframe's parent and keep the iframe at `height: 100%`. Check every ancestor if you use a percentage height.
+
+## Backstage
+
+If your host application is Backstage, use the [EventCatalog Backstage plugin](/docs/plugins/backstage/overview). It supplies React components, resolves EventCatalog resources from Backstage entity annotations, and constructs the embed URLs for you.

package/dist/docs/development/customization/_category_.json

@@ -7,6 +7,6 @@
     "type": "generated-index",
     "slug": "development/customization",
     "title": "Customization Documentation",
-    "description": "Learn how to customize EventCatalog."
+    "description": "Customize EventCatalog and embed its documentation and visualizations in other applications."
   }
 }

package/dist/docs/development/deployment/build-and-deploy.md

@@ -32,6 +32,10 @@ This will output one directory
 
 - `dist` - Your EventCatalog as Static HTML
 
+### Link validation
+
+Static builds check internal links and anchors and report warnings by default. See [link validation](/docs/development/deployment/link-validation) to fail builds on broken links, ignore destinations, or disable the check.
+
 ### Passing custom options
 
 <AddedIn version="2.16.5" />

package/dist/docs/development/deployment/hosting-options.md

@@ -22,7 +22,7 @@ By default EventCatalog will build a static website.
 
 Here are some guides and places you can host static content
 
-- [Host with Docker](#hosting-with-docker)
+- [Host with Docker](#hosting-static-website-with-docker)
 - [Deploy to NextJS](https://nextjs.org/docs/deployment)
 - [Host in AWS S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/WebsiteHosting.html)
 

package/dist/docs/development/deployment/link-validation.md

@@ -0,0 +1,105 @@
+---
+sidebar_position: 5
+sidebar_label: Link validation
+title: Link validation
+description: Catch broken links and anchors before they reach production
+---
+
+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), 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`](/docs/api/config#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`](/docs/api/config#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](/docs/development/deployment/build-and-deploy). It's skipped when running in [SSR mode](/docs/development/deployment/build-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.
+
+```js title="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.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  linkValidation: {
+    onBrokenLinks: 'error',
+    onBrokenAnchors: 'ignore',
+  },
+};
+```
+
+Turn the whole feature off by setting `linkValidation` to `false`.
+
+```js title="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`](/docs/api/config#linkvalidationignore) for how paths are matched.
+
+```js title="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.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  linkValidation: {
+    onBrokenLinks: process.env.CI ? 'error' : 'warn',
+    onBrokenAnchors: process.env.CI ? 'error' : 'warn',
+  },
+};
+```
+
+```yaml title=".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
+
+- [`eventcatalog.config.js` reference](/docs/api/config#linkValidation) for the full list of options
+- [Resource references](/docs/development/components/resource-references) for linking to catalog resources