@eventcatalog/core 4.1.3 → 4.1.4

package/dist/docs/development/guides/resources/messages/04-message-channels/05-reference.md

@@ -0,0 +1,177 @@
+---
+keywords:
+- EventCatalog channels
+- Channel frontmatter
+sidebar_label: Reference
+title: Message channels reference
+description: Frontmatter fields, paths, and routes for channels in EventCatalog.
+---
+
+This page lists the fields, paths, and routes supported by channels.
+
+## Paths
+
+Channels can be created in any `channels` folder:
+
+```txt
+/channels/{Channel Name}/index.mdx
+/domains/{Domain Name}/channels/{Channel Name}/index.mdx
+/services/{Service Name}/channels/{Channel Name}/index.mdx
+```
+
+Versioned channels use:
+
+```txt
+/channels/{Channel Name}/versioned/{version}/index.mdx
+```
+
+## Routes
+
+| Route | Description |
+|-------|-------------|
+| `/docs/channels/{channel-id}/{version}` | Channel documentation page. |
+| `/visualiser/channels/{channel-id}/{version}` | Channel resource diagram. |
+
+## Required fields
+
+### `id` {#id}
+
+- Type: `string`
+
+Unique id of the channel. EventCatalog uses this for URLs and resource references.
+
+```md title="Example"
+---
+id: orders-topic
+---
+```
+
+### `name` {#name}
+
+- Type: `string`
+
+Display name of the channel.
+
+```md title="Example"
+---
+name: Orders Topic
+---
+```
+
+### `version` {#version}
+
+- Type: `string`
+
+Version of the channel documentation.
+
+```md title="Example"
+---
+version: 1.0.0
+---
+```
+
+## Optional fields
+
+### `summary` {#summary}
+
+- Type: `string`
+
+Short description of the channel.
+
+```md title="Example"
+---
+summary: Kafka topic that carries ordering events.
+---
+```
+
+### `owners` {#owners}
+
+- Type: `array`
+
+An array of team or user ids that own the channel.
+
+```md title="Example"
+---
+owners:
+  - ordering-platform
+---
+```
+
+### `address` {#address}
+
+- Type: `string`
+
+Broker address, topic, stream, queue, or route.
+
+```md title="Example"
+---
+address: orders.events
+---
+```
+
+### `protocols` {#protocols}
+
+- Type: `array`
+
+Protocols used by the channel, such as Kafka, HTTP, or AMQP.
+
+```md title="Example"
+---
+protocols:
+  - kafka
+---
+```
+
+### `deliveryGuarantee` {#deliveryGuarantee}
+
+- Type: `at-most-once`, `at-least-once`, or `exactly-once`
+
+Delivery guarantee for messages on the channel.
+
+```md title="Example"
+---
+deliveryGuarantee: at-least-once
+---
+```
+
+### `parameters` {#parameters}
+
+- Type: `object`
+
+Parameter definitions for templated channel addresses.
+
+```md title="Example"
+---
+parameters:
+  region:
+    description: Deployment region for the topic.
+---
+```
+
+
+### `badges` {#badges}
+
+- Type: `array`
+
+Badges rendered on the channel page.
+
+```md title="Example"
+---
+badges:
+  - content: Kafka
+    backgroundColor: purple
+    textColor: purple
+---
+```
+
+## Delivery guarantee
+
+Use `deliveryGuarantee` to describe how messages are delivered on the channel.
+
+Supported values are `at-most-once`, `at-least-once`, and `exactly-once`.
+
+```md
+---
+deliveryGuarantee: at-least-once
+---
+```

package/dist/docs/development/guides/{channels → resources/messages/04-message-channels}/_category_.json

@@ -1,11 +1,11 @@
 {
-  "label": "Channels",
+  "label": "Message Channels",
   "position": 4,
   "collapsible": true,
   "collapsed": true,
   "link": {
     "type": "generated-index",
-    "slug": "/channels",
+    "slug": "/messages/message-channels",
     "description": "A collection of guides to help you understand channels and how they work with EventCatalog."
   }
-}
+}

package/dist/docs/development/guides/{messages/common/04-versioning.md → resources/messages/08-versioning-and-lifecycle/01-version-messages.md}

@@ -2,11 +2,13 @@
 keywords:
 - versioning
 - events
-sidebar_label: Versioning messages
-title: Versioning
-description: Learn how to version events
+sidebar_label: Version messages
+title: Version messages
+description: Learn how to version messages.
 ---
 
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
 All content in EventCatalog can be versioned. This allows you to keep historic versions of content which can give context to users why things are changing.
 
 ## How to version a message
@@ -20,8 +22,41 @@ All content in EventCatalog can be versioned. This allows you to keep historic v
 1. Bump the version of the `index.mdx` file in the route of the domain.
     - Example `/events|commands|queries/InventoryOutOfStock/index.mdx`, change the `version` to `0.0.2`
 
+<ProjectTree
+  items={[
+    {
+      name: 'events',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'InventoryOutOfStock',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            { name: 'index.mdx', highlight: true },
+            {
+              name: 'versioned',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: '0.0.1',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
 ## How to navigate to versions
 
 EventCatalog will automatically create links for you within your latest version of your document. Users will also be able to navigate to any version by adding the version in the url (e.g /docs/events|commands|queries/InventoryOutOfStock/1.0.2 would load the 1.0.2 version of this service).
 
-![Example](../../img/domains/versioned.png)
+![Example](../../../img/domains/versioned.png)

package/dist/docs/development/guides/{messages/common/05-changelog.md → resources/messages/08-versioning-and-lifecycle/02-add-changelog.md}

@@ -2,14 +2,14 @@
 keywords:
     - changelog 
     - events
-sidebar_label: Message changelogs
-title: Event changelogs 
-description: Adding changelogs to your events
+sidebar_label: Add a changelog
+title: Add a changelog
+description: Add changelogs to messages.
 ---
 
-EventCatalog supports changelogs for [domains](/docs/domains), [services](/docs/services) and [messages](/docs/messages).
+EventCatalog supports changelogs for [domains](/docs/domains), [services](/docs/development/guides/resources/services/introduction) and [messages](/docs/development/guides/resources/messages/what-are-messages).
 
-When you [version a message](/docs/development/guides/messages/common/versioning) in EventCatalog, you can also attach a `changelog.mdx` to that message or versioned message.
+When you [version a message](/docs/development/guides/resources/messages/versioning-and-lifecycle/version-messages) in EventCatalog, you can also attach a `changelog.mdx` to that message or versioned message.
 
 ### Adding a changelog
 
@@ -70,4 +70,3 @@ Changelogs can provide your team with the context behind the reasons and choices
 Changelogs are visualized by EventCatalog.
 
 
-

package/dist/docs/development/guides/{messages/common/02-deprecating.md → resources/messages/08-versioning-and-lifecycle/03-deprecate-messages.md}

@@ -3,8 +3,8 @@ keywords:
 - EventCatalog
 - messages  
 - deprecating
-sidebar_label: Deprecating messages
-title: Deprecating messages
+sidebar_label: Deprecate messages
+title: Deprecate messages
 description: Deprecating messages with EventCatalog.
 sidebar_position: 4
 ---
@@ -60,11 +60,11 @@ Deprecated as an object is recommended, as it gives your users more information
 
 Example of resource that will be deprecated:
 
-  ![Deprecating messages](../../img/deprecated/will-be-deprecated.png) 
+  ![Deprecating messages](../../../img/deprecated/will-be-deprecated.png) 
 
 Example of resource that is deprecated:
 
-![Deprecating messages](../../img/deprecated/is-deprecated.png) 
+![Deprecating messages](../../../img/deprecated/is-deprecated.png) 
 
 #### Demo
 

package/dist/docs/development/guides/resources/messages/08-versioning-and-lifecycle/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Versioning & lifecycle",
+  "position": 6,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/messages/versioning-and-lifecycle",
+    "description": "Version, deprecate, and document changes to messages."
+  }
+}

package/dist/docs/development/guides/{messages/common/02-examples.md → resources/messages/09-add-usage-examples.md}

@@ -4,15 +4,14 @@ keywords:
     - events
     - commands
     - queries
-sidebar_label: Adding usage examples
-title: Message examples
+sidebar_label: Add usage examples
+title: Add usage examples
 description: Add usage examples to your messages for quick reference.
-sidebar_position: 3
+sidebar_position: 7
 ---
 
 import AddedIn from '@site/src/components/MDX/AddedIn';
-
-<AddedIn version="3.22.1" />
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
 
 EventCatalog lets you attach example payloads to any message (event, command, or query). This can help your team understand exactly how your schemas can be used
 in your architecture and provide them with real examples.
@@ -25,15 +24,35 @@ Examples appear in the Schema Explorer under a **Usage Examples** tab alongside
 
 Create an `examples/` folder inside your message directory and drop in any example files. EventCatalog supports any text-based format: JSON, YAML, XML, Protobuf, and more.
 
-```
-events/
-  OrderCreated/
-    index.mdx
-    schema.json
-    examples/
-      basic-order.json
-      international-order.json
-```
+<ProjectTree
+  items={[
+    {
+      name: 'events',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'OrderCreated',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            { name: 'index.mdx' },
+            { name: 'schema.json' },
+            {
+              name: 'examples',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                { name: 'basic-order.json', highlight: true },
+                { name: 'international-order.json', highlight: true },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
 
 The **Usage Examples** tab appears automatically when at least one example file is present. No frontmatter changes are required.
 
@@ -41,14 +60,32 @@ The **Usage Examples** tab appears automatically when at least one example file
 
 You can use nested folders to group related examples. EventCatalog displays all files in a flat list regardless of folder depth.
 
-```
-examples/
-  domestic/
-    basic-order.json
-  international/
-    eu-order.json
-    apac-order.json
-```
+<ProjectTree
+  items={[
+    {
+      name: 'examples',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'domestic',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'basic-order.json', highlight: true }],
+        },
+        {
+          name: 'international',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            { name: 'eu-order.json', highlight: true },
+            { name: 'apac-order.json', highlight: true },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
 
 ### Add metadata