Channel frontmatter API

Added in eventcatalog@2.13.0

Overview

Channels are just markdown files, with this comes the use of Content, MDX components and also front-matter.

Here is an example of the channel frontmatter you will find in your /channels folder.

/channels/inventory.{env}.events/index.mdx (example)

---
# id of your channel, used for slugs and references in EventCatalog.
id: inventory.{env}.events

# Display name of the channel, rendered in EventCatalog
name: Inventory Events Channel

# Version of the channel
version: 1.0.0

# Short summary of your channel
summary: |
  Central event stream for all inventory-related events including stock updates, allocations, and adjustments

# Optional owners, references teams or users
owners:
  - dboyne

# address of the channel
# supports parameters in the address  
address: inventory.{env}.events

# list of protocols for the channel
# see https://eventcatalog.dev/docs/development/guides/channels/introduction#protocols
protocols: 
  - kafka

# Optional list of parameters for the channel
# This example shows the `env` value in the channel name can be `dev, stg, prod`.
parameters:
  env:
    enum:
      - dev
      - stg
      - prod
    description: 'Environment to use'
---

### Overview
The Inventory Events channel is the central stream for all inventory-related events across the system. This includes stock level changes, inventory allocations, adjustments, and stocktake events. Events for a specific SKU are guaranteed to be processed in sequence when using productId as the partition key.

<ChannelInformation />

Required fields

id

• Type: string

Unqiue id of the channel. EventCatalog uses this for references and slugs.

Example

---
  id: inventory.{env}.events
---

name

• Type: string

Name of the channel this is used to display the name on the UI.

Example

---
  name: Inventory events
---

version

• Type: string

Version of the channel.

Example

---
  version: 0.0.1
---

Optional fields

summary

Short summary of your channel.

Example

---
  summary: |
    Central event stream for all inventory-related events including stock updates, allocations, and adjustments
---

address

Address of the channel.

Example

---
  # example of dynamic address
  address: inventory.{env}.events

  # static address
  address: MyEventBus
  
---

protocols

Protocol/s of the channel.

Example

---
  # example of a kafka channel
  protocol: 
    - kafka

  # example of a channel that is http, mqtt or kafka (if you ever wanted too...)
  protocol:
    - http
    - mqtt
    - kafka
  
---

parameters

Parameters for your channel.

Example

---
  parameters:
    # any string value
    env:
      # list of possible values for the parameter
      enum:
        - dev
        - stg
        - prod
      # description for the parameter (optional)
      description: 'Environment to use'
      # list of examples (optional)
      examples
        - dev
        - stg
      # default value for channel
      default
        - dev
---

owners

An array of user ids that own the channel.

Example

---
  owners:
    - dboyne
    - mSmith
---

badges

An array of badges that get rendered on the page.

Example

---
  badges:
    - content: My badge
      backgroundColor: blue
      textColor: blue
      # Optional icon to display (from https://heroicons.com/)
      # Or the name of the broker (e.g Kafka, EventBridge, etc)
      icon: BoltIcon
---

repository

Added in eventcatalog@2.11.2

Repository language and code url for the channel.

Example

---
  repository:
    language: JavaScript
    url: https://github.com/event-catalog/pretend-shipping-service
---

editUrl

Added in eventcatalog@2.49.4

Override the default edit url for the page. This is used to navigate the user to the edit page for the page (e.g GitHub, GitLab url).

Example

---
  editUrl: https://github.com/event-catalog/eventcatalog/edit/main/channels/inventory.{env}.events/index.mdx
---

detailsPanel

Added in eventcatalog@2.53.0

Override the default details panel for the page. You can use this show/hide areas of the details panel.

Example

---
  detailsPanel:
    producers:
      visible: false
    consumers:
      visible: false
    channels:
      visible: false
    versions:
      visible: false
---

Options:

Property	Type	Required	Description
producers	object	No	An object with a visible property to show/hide the producers section
consumers	object	No	An object with a visible property to show/hide the consumers section
messages	object	No	An object with a visible property to show/hide the messages section
protocols	object	No	An object with a visible property to show/hide the protocols section
parameters	object	No	An object with a visible property to show/hide the parameters section
versions	object	No	An object with a visible property to show/hide the versions section
repository	object	No	An object with a visible property to show/hide the repository section (e.g GitHub, GitLab url)
owners	object	No	An object with a visible property to show/hide the owners section
changelog	object	No	An object with a visible property to show/hide the changelog button

attachments

Added in eventcatalog@2.57.2

An array of attachments for this resource type.

Example

---
  attachments:
    - url: https://example.com/adr/001
      title: ADR-001 - Use Kafka for asynchronous messaging
      description: Learn more about why we chose Kafka for asynchronous messaging in this architecture decision record.
      type: 'architecture-decisions'
      icon: FileTextIcon
    - https://example.com/adr/002
---

Options:

The attachments can be a url (string) or an object with additional properties.

Object properties:

Property	Type	Required	Description
url	string	Yes	The url of the attachment
title	string	optional	The title of the attachment
description	string	optional	The description of the attachment
type	string	optional	The type of the attachment, this will be used to group attachments together in the UI
icon	string	optional	The icon of the attachment, you can pick from the lucide icons library.