@eventcatalog/core 3.34.0 → 3.35.1

package/dist/docs/development/bring-your-own-documentation/custom-pages/03-components.md

@@ -0,0 +1,46 @@
+---
+sidebar_position: 3
+keywords:
+    - components 
+    - domains
+sidebar_label: Components
+title: Components
+description: Component list for custom pages 
+---
+
+You can add custom EventCatalog components to your custom pages.
+
+[See the list of components and how to use them](/docs/development/components/using-components).
+
+You can also added components designed specifically for custom documentation.
+
+### Embed EventCatalog Visualizer (NodeGraph)
+
+In your custom documentation pages you can embed the EventCatalog Visualizer (NodeGraph) using the `NodeGraph` component.
+
+![Example](./img/custom-docs-with-nodegraph.png)
+
+This let's you embed any visualization (domain, service, message) into your custom documentation page.
+
+To embed the NodeGraph component, you need to use the component, and pass in the `id` of the resource, `version` and `type`.
+
+```md
+This is my custom documentation page, here is a NodeGraph:
+
+<!-- Here we embed the NodeGraph component, passing in the id, version and type of the resource -->
+<!-- This exammple will render a domain called "Orders" with the version "1.0.0" -->
+<NodeGraph id="Orders" version="1.0.0" type="domain" />
+
+## Getting Started
+
+Rest of my markdown content...
+```
+
+#### NodeGraph props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `id` | string | Yes | The id of the resource (domain, service, or message) |
+| `version` | string | Yes | The version of the resource |
+| `type` | string | Yes | The type of the resource (domain, service, command, event, query) |
+

package/dist/docs/development/bring-your-own-documentation/custom-pages/04-owners.md

@@ -0,0 +1,45 @@
+---
+sidebar_position: 4
+keywords:
+- EventCatalog
+- channels 
+- owners
+sidebar_label: Owners
+title: Adding custom page owners
+description: Adding owners to custom pages with EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.33.0" />
+
+Owners in EventCatalog are either **users** or **teams** and are **optional**.
+
+To add an owner or a team, you need to add the user or team to the owners field of the custom page.
+
+## Adding owners using frontmatter
+
+To add owners within a custom page you need to add them to the `owners` array within your custom page frontmatter API.
+
+You need to add the `id` of the owner.
+
+```md title="/docs/guides/creating-a-new-producer/index.mdx (example)"
+---
+id: OrderChannel
+... # other custom page frontmatter
+owners:
+    - dboyne # represents a user
+    - webTeam # represents a team
+---
+
+<!-- Markdown contents... -->
+
+```
+
+Assigning owners to your custom pages can provide others with context of who owns this custom page and how to contact them.
+
+:::tip Creating users and teams
+    EventCatalog gives you the ability to create users and teams. You can read the documentation to get started.
+:::
+
+

package/dist/docs/development/bring-your-own-documentation/custom-pages/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Global documentation",
+  "position": 2,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "guides/bring-your-own-documentation/custom-pages",
+    "description": "Add catalog-wide custom documentation pages to your catalog."
+  }
+}

package/dist/docs/development/bring-your-own-documentation/resource-docs/01-introduction.md

@@ -0,0 +1,34 @@
+---
+sidebar_position: 1
+sidebar_label: Introduction
+title: Resource-level documentation
+description: Attach documentation pages to any resource in your catalog.
+keywords:
+  - EventCatalog resource-level documentation
+  - ADRs
+  - runbooks
+  - resource-level documentation
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.15.0" />
+
+:::info Scale plan required
+Resource-level documentation requires an [EventCatalog Scale plan](https://eventcatalog.dev/pricing).
+:::
+
+Resource-level documentation lets you attach documentation pages directly to any resource in your catalog. Instead of keeping ADRs, runbooks, contracts, and guides in a separate tool, you can place them alongside the resource they describe.
+
+![](./img/docs.png)
+
+Attached docs appear in the resource sidebar, grouped by custom defined types, so readers can navigate between the resource overview and its supporting documentation without leaving the catalog.
+
+### Supported resources
+
+Resource-level documentation can be attached to any of the following resource types:
+
+- Domains and subdomains
+- Services
+- Events, Commands, Queries
+- Flows, Channels, Containers, Entities, Data products

package/dist/docs/development/bring-your-own-documentation/resource-docs/02-adding-resource-docs.md

@@ -0,0 +1,143 @@
+---
+sidebar_position: 2
+sidebar_label: Adding resource-level documentation
+title: Adding resource-level documentation
+description: Place MDX files in a docs/ directory alongside any resource.
+keywords:
+  - EventCatalog resource docs
+  - ADRs
+  - runbooks
+  - resource documentation
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.15.0" />
+
+:::info Scale plan required
+Resource docs require an [EventCatalog Scale plan](https://eventcatalog.dev/pricing).
+:::
+
+## Adding resource-level documentation
+
+Place `.mdx` files inside a `docs/` directory under any resource. EventCatalog will automatically pick them up and display them in the resource's sidebar.
+
+```
+services/
+└── OrdersService/
+    ├── index.mdx
+    └── docs/
+        ├── 01-deployment.mdx
+        └── 02-incident-response.mdx
+```
+
+### Frontmatter properties
+
+Each doc file supports the following frontmatter.
+
+| Property  | Required | Description                                      |
+|-----------|----------|--------------------------------------------------|
+| `title`   | No       | Display name of the doc. Defaults to the file name. |
+| `summary` | No       | Short description shown below the title.        |
+| `type`    | No       | Groups the doc in the sidebar. Defaults to the folder name, or `pages` if placed directly in `docs/`. |
+| `version` | No       | Doc version. Defaults to the resource version.  |
+| `order`   | No       | Explicit sort position within the group.        |
+| `badges`  | No       | Badges shown on the doc page.                   |
+
+
+#### Example of resource-level documentation
+
+```mdx title="services/OrdersService/docs/01-deployment.mdx"
+---
+title: Deployment runbook
+summary: Step-by-step guide for deploying the Orders service to production.
+version: 1.0.0
+---
+
+## Pre-deployment checklist
+
+1. Confirm staging tests pass.
+2. Notify the on-call engineer.
+...
+```
+
+### Order docs with numeric prefixes
+
+Files are sorted alphabetically by default. Prefix the file name with a number to control the order.
+
+```
+docs/
+├── 01-deployment.mdx
+├── 02-incident-response.mdx
+└── 03-disaster-recovery.mdx
+```
+
+The numeric prefix is stripped from the doc's ID and URL, so `01-deployment.mdx` is accessible at `.../pages/deployment`.
+
+You can also set an explicit `order` value in frontmatter, which takes precedence over the numeric prefix.
+
+### Use with domains and subdomains
+
+Domains and subdomains follow the same pattern.
+
+```
+domains/
+└── E-Commerce/
+    ├── index.mdx
+    └── docs/
+        └── 01-bounded-context.mdx
+    └── subdomains/
+        └── Orders/
+            ├── index.mdx
+            └── docs/
+                └── 01-order-processing.mdx
+```
+
+## Navigate to a resource doc
+
+Resource docs are served at:
+
+```
+http://localhost:3000/docs/{resourceType}/{resourceId}/{version}/{docType}/{docId}
+```
+
+For example, `01-deployment.mdx` for `OrdersService` version `1.0.0` would be at:
+
+```
+http://localhost:3000/docs/services/OrdersService/1.0.0/pages/deployment
+```
+
+## Grouping docs by type
+
+Docs can be organised into groups using subdirectories inside `docs/`. Each subdirectory becomes a **doc type** and gets its own section in the resource sidebar.
+
+```
+services/
+└── OrdersService/
+    ├── index.mdx
+    └── docs/
+        ├── adrs/
+        │   └── 01-use-postgres.mdx
+        ├── runbooks/
+        │   ├── 01-deployment.mdx
+        │   └── 02-incident-response.mdx
+        └── guides/
+            └── on-call.mdx
+```
+
+The folder name is used as the group label by default. The built-in types `adrs`, `runbooks`, `contracts`, `troubleshooting`, and `guides` are automatically formatted with friendly labels in the sidebar.
+
+You can override the type for any doc using the `type` frontmatter field, regardless of which folder it lives in:
+
+```mdx title="services/OrdersService/docs/adrs/01-use-postgres.mdx"
+---
+title: Use PostgreSQL for order storage
+type: architecture-records
+---
+```
+
+The type resolution order is:
+
+1. `type` frontmatter — takes highest precedence
+2. Folder name — used when `type` is not set
+3. `pages` — fallback when the doc is placed directly in `docs/` with no subfolder

package/dist/docs/development/bring-your-own-documentation/resource-docs/03-categories.md

@@ -0,0 +1,68 @@
+---
+sidebar_position: 3
+sidebar_label: Configure categories
+title: Configure categories
+description: Control sidebar labels and ordering for doc type groups using category files.
+keywords:
+  - EventCatalog resource docs categories
+  - category.json
+  - resource documentation
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.x.0" />
+
+When you group resource docs into subdirectories, each subdirectory becomes a section in the resource sidebar. By default, the section label is the folder name and sections are sorted alphabetically.
+
+**Categories** let you customise this — you can give a group a friendlier display label and control the order it appears relative to other groups, without renaming the folder.
+
+## Category files
+
+Place a `category.json` file inside any doc type folder to configure its sidebar label and position.
+
+```
+services/
+└── OrdersService/
+    └── docs/
+        └── runbooks/
+            ├── category.json
+            ├── 01-deployment.md
+            └── 02-incident-response.md
+```
+
+```json title="services/OrdersService/docs/runbooks/category.json"
+{
+  "label": "Runbooks",
+  "position": 1
+}
+```
+
+### Category file properties
+
+| Property   | Required | Description                                                      |
+|------------|----------|------------------------------------------------------------------|
+| `label`    | No       | Display name for the doc type group in the sidebar.             |
+| `position` | No       | Sort order of the group relative to other doc type groups.      |
+
+### Use `_category_.json` as an alternative
+
+EventCatalog also accepts `_category_.json` as the file name. When both files exist in the same folder, `category.json` takes precedence.
+
+### Control group ordering
+
+Set `position` on each group to control the order they appear in the sidebar. Groups without a position are sorted alphabetically after positioned groups.
+
+```json title="docs/adrs/category.json"
+{
+  "label": "Architecture decisions",
+  "position": 1
+}
+```
+
+```json title="docs/runbooks/category.json"
+{
+  "label": "Runbooks",
+  "position": 2
+}
+```

package/dist/docs/development/bring-your-own-documentation/resource-docs/04-versioning.md

@@ -0,0 +1,45 @@
+---
+sidebar_position: 4
+sidebar_label: Version documents
+title: Version documents
+description: Keep historical versions of resource docs alongside versioned resources.
+keywords:
+  - EventCatalog resource docs versioning
+  - versioned documentation
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.15.0" />
+
+## How versioning works
+
+Resource docs are associated with a specific version of a resource. When you version a resource, the docs in that resource's `docs/` directory apply to the current (latest) version.
+
+Previous versions of a doc are stored inside the resource's `versioned/` directory, following the same pattern used for versioned resources.
+
+```
+services/
+└── OrdersService/
+    ├── index.mdx
+    ├── docs/
+    │   └── runbooks/
+    │       └── 01-deployment.md        ← current version
+    └── versioned/
+        └── 0.0.2/
+            └── docs/
+                └── runbooks/
+                    └── 01-deployment.md   ← older version
+```
+
+## Navigate between versions
+
+When a doc has multiple versions, a **Versions** panel is shown in the right-hand column of the doc page. You can use it to jump to any historical version of that document.
+
+A banner is shown at the top of older versions to make clear that a newer version exists.
+
+## Doc version vs resource version
+
+A doc file's `version` frontmatter field refers to the **doc's own version**, not the resource version. This allows a doc to be updated independently of the resource it belongs to.
+
+If `version` is omitted from frontmatter, EventCatalog infers it from the resource version the doc file lives under.

package/dist/docs/development/bring-your-own-documentation/resource-docs/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Resource-level documentation",
+  "position": 3,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "guides/bring-your-own-documentation/resource-docs",
+    "description": "Attach documentation pages directly to any resource in your catalog."
+  }
+}

package/dist/docs/development/components/04-snippets.md

@@ -0,0 +1,134 @@
+---
+sidebar_position: 6
+keywords:
+- snippets
+sidebar_label: Reusable snippets
+title: Reusable snippets
+description: Understanding how to use snippets with EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.48.0" />
+
+Keep your documentation consistent and maintainable with reusable snippets.
+
+In EventCatalog, staying DRY (Don't Repeat Yourself) isn't just for code—it's for documentation too. If you're repeating the same content across multiple pages, consider using a snippet to centralize it. This makes your docs easier to manage and keeps everything in sync.
+
+## Creating a Snippet
+
+:::important
+Snippets must live in the `/snippets` directory to be recognized by EventCatalog. Files in this folder won’t generate standalone pages—they’re designed to be imported wherever needed.
+:::
+
+## Basic Usage
+
+1. Create your snippet
+
+```md title="snippets/my-snippet.mdx"
+Hello world! This is my content I want to reuse across pages. 
+```
+
+2. Import and use in any page:
+
+```markdown title="/domains/my-domain/index.mdx"
+---
+id: E-Commerce
+name: E-Commerce
+version: 1.0.0
+---
+
+<!-- Import the snippet from the snippets directory -->
+import MySnippet from '@eventcatalog/snippets/my-snippet.mdx';
+
+<!-- Use the snippet anywhere on your page -->
+<MySnippet />
+
+```
+
+
+## Passing Variables to Snippets
+
+Snippets can accept props for dynamic content. Here's how:
+
+1. Create a snippet with props:
+
+```md title="snippets/my-snippet.mdx"
+Hello {props.name}! This is my content I want to reuse across pages. 
+```
+
+2. Import and use with props:
+
+```md title="/domains/my-domain/index.mdx"
+---
+id: E-Commerce
+name: E-Commerce
+version: 1.0.0
+---
+
+<!-- Import the snippet from the snippets directory -->
+import MySnippet from '@eventcatalog/snippets/my-snippet.mdx';
+
+<!-- Use the snippet with props -->
+<MySnippet name="John" />
+
+```
+
+## Exporting Variables
+
+You can also export constants or objects from a snippet for use elsewhere.
+
+1. Export a variable from the snippet:
+
+```md title="snippets/my-snippet.mdx"
+export const platformName = 'EventCatalog';
+export const colors = { primary: '#000000' };
+```
+
+2. Import the variable in your page:
+
+```md title="/domains/my-domain/index.mdx"
+---
+id: E-Commerce
+name: E-Commerce
+version: 1.0.0
+---
+
+<!-- Import the snippet from the snippets directory -->
+import { platformName, colors } from '/snippets/constants.mdx';
+
+<!-- Use the variable -->
+<p>Hello {platformName}!</p>
+<p>The primary color is {colors.primary}.</p>
+
+```
+
+## JSX-Based Snippets
+
+Need something more dynamic? Use a snippet as a JSX component:
+
+```md title="snippets/my-snippet.mdx"
+export default function MySnippet({ name }) {
+  return <div>Hello {name}!</div>;
+}
+```
+
+Then import and use it like this:
+
+```md title="/domains/my-domain/index.mdx"
+---
+id: E-Commerce
+name: E-Commerce
+version: 1.0.0
+---
+
+<!-- Import the snippet from the snippets directory -->
+import MySnippet from '@eventcatalog/snippets/my-snippet.mdx';
+
+<!-- Use the snippet as a JSX component -->
+<MySnippet name="John" />
+
+```
+
+
+

package/dist/docs/development/components/05-using-components.md

@@ -0,0 +1,67 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Introduction
+title: Using components
+description: Understanding components
+---
+
+EventCatalog uses [MDX](https://mdxjs.com/) under the hood. This gives you the ability to include predefined components inside your contents.
+
+You can add components to your domains, services or messages.
+
+## Quick links
+
+In addition to components, use wiki-style syntax for inline resource references with interactive tooltips:
+
+```md
+The [[service|OrdersService]] processes [[event|OrderCreated]] messages.
+```
+
+See [Resource references](/docs/development/components/resource-references) for details.
+
+### Example
+
+You can include any component inside the markdown content. This example renders an Accordion component within an event.
+
+```md title="/events/Orders/OrderAmended/index.mdx"
+---
+id: OrderAmended
+name: Order amended
+version: 0.0.1
+summary: |
+  Indicates an order has been changed
+owners:
+    - dboyne
+    - msmith
+badges:
+    - content: Recently updated!
+      backgroundColor: green
+      textColor: green
+    - content: Channel:Apache Kafka
+      backgroundColor: yellow
+      textColor: yellow
+---
+
+## Overview
+
+Event is raised when an order has been changed.
+
+<Accordion title="Learn how to raise this event">
+  You can run the following command to raise this event.
+
+  ```sh
+  bin/kafka-topics.sh --create --topic OrderAmended --bootstrap-server localhost:9092 --partitions 1 --replication-factor 1
+  ``
+</Accordion>
+
+```
+
+
+![Example](./img/accordian.png)
+
+
+
+
+