@eventcatalog/core 4.1.2 → 4.1.4

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

@@ -8,14 +8,16 @@ description: Customize documentation in EventCatalog
 ---
 
 import AddedIn from '@site/src/components/MDX/AddedIn';
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
 
 <AddedIn version="2.33.0" />
+<PlanBanner plan="Scale" />
 
 <iframe width="100%" height="415" src="https://www.youtube.com/embed/auzmEf0AdJg?si=wHe-3X6b6uLN39sB" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
 
 ---
 
-Global documentation is a way to add catalog-wide custom documentation pages to your catalog.
+High level documentation is a way to add catalog-wide custom documentation pages to your catalog.
 
 This can be a great way to extend your catalog beyond what is provided, and bring your own documentation to EventCatalog, rather than having documentation spread across multiple tools.
 
@@ -23,9 +25,8 @@ This can be a great way to extend your catalog beyond what is provided, and brin
 ![Example](./img/custom-docs.png)
 <a class="block" href="https://demo.eventcatalog.dev/docs/custom/technical-architecture-design/architecture-decision-records/published/01-api-gateway-pattern">View demo</a>
 
-Global documentation is not limited, here are some examples of what you can do:
+High level documentation is not limited, here are some examples of what you can do:
 
-- Document architecture decision records
 - Document infrastructure & operations
 - Document CI/CD pipelines
 - Document user journeys
@@ -38,23 +39,23 @@ Global documentation is not limited, here are some examples of what you can do:
 
 It's really up to you what you add here.
 
-### How global documentation can help
+### How high level documentation can help
 
 EventCatalog provides the ability to document your architecture with domains, services and messages. 
 
 Users still have third party tools to document other parts of their architecture (e.g confluence, Google docs, etc), so this is an option to help you keep all your documentation in one place.
 
-### What can I do with global documentation in EventCatalog?
+### What can I do with high level documentation in EventCatalog?
 
 You can add any custom documentation to your catalog, this also gives you access to the [EventCatalog components](/docs/components).
 Your custom documentation is powered by markdown, meaning you can use EventCatalog components within your documentation.
 
-### Roadmap for global documentation
+### Roadmap for high level documentation
 
-This is the initial version of global documentation in EventCatalog.
+This is the initial version of high level documentation in EventCatalog.
 
 We plan to add the following features:
 
 - Add support to embed EventCatalog visualizations into your documentation pages
 - Embed EventCatalog resources into your custom documentation pages
-- Add ability to add runtime blocks into your pages (e.g making requests to get third party data to display)
+- Add ability to add runtime blocks into your pages (e.g making requests to get third party data to display)

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

@@ -1,64 +1,104 @@
 ---
 sidebar_position: 1
 keywords:
-- EventCatalog global documentation
-sidebar_label: Adding global documentation
-title: Adding global documentation
-description: Adding global documentation to your EventCatalog
+- EventCatalog high level documentation
+sidebar_label: Adding high level documentation
+title: Adding high level documentation
+description: Adding high level documentation to your EventCatalog
 ---
 
 import AddedIn from '@site/src/components/MDX/AddedIn';
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
 
 <AddedIn version="2.33.0" />
+<PlanBanner plan="Scale" />
 
 ## Getting started
 
-Global documentation requires a [Starter or Scale plan](https://eventcatalog.dev/pricing), you can get a 14 day free trial to test it out at [EventCatalog Cloud](https://eventcatalog.cloud). Once you have a license key you can start to use the feature.
+High level documentation requires an EventCatalog Scale license key. You can get a 30-day free trial from [EventCatalog Cloud](https://eventcatalog.cloud).
 
-## Adding global documentation
+## Adding high level documentation
 
-Global documentation is split into two parts:
+High level documentation is split into two parts:
 
 1. [Creating your documentation (markdown files)](#creating-your-documentation)
 2. [Configuring your sidebar (eventcatalog.config.js)](#configuring-your-sidebar)
 
 ### Creating documentation
 
-Global documentation is stored in the `/docs` folder in your catalog [(see example on GitHub)](https://github.com/event-catalog/eventcatalog/tree/main/examples/default/docs), and can be accessed via the url `/docs/custom/`.
+High level documentation is stored in the `/docs` folder in your catalog [(see example on GitHub)](https://github.com/event-catalog/eventcatalog/tree/main/examples/default/docs), and can be accessed via the url `/docs/custom/`.
 
 All documentation is a `.mdx` (markdown extended) file. You can organize these however you want, for example:
 
-```
-docs/
-├── architecture-decision-records/
-│   ├── drafts/
-│   │   ├── 01-introduction.mdx
-│   │   ├── 02-example-record.mdx
-│   ├── published/
-│   │   ├── 01-introduction.mdx
-│   │   ├── 02-example-record.mdx
-│   ├── examples/
-│   │   ├── 01-introduction.mdx
-│   │   ├── 02-example-record.mdx
-├── runbooks/
-│   ├── 01-introduction.mdx
-│   ├── 02-deployment-procedure.mdx
-│   ├── 03-disaster-recovery.mdx
-│   ├── 04-incident-response.mdx
-
-```
+<ProjectTree
+  items={[
+    {
+      name: 'docs',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'architecture-decision-records',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'drafts',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                { name: '01-introduction.mdx' },
+                { name: '02-example-record.mdx' },
+              ],
+            },
+            {
+              name: 'published',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                { name: '01-introduction.mdx' },
+                { name: '02-example-record.mdx' },
+              ],
+            },
+            {
+              name: 'examples',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                { name: '01-introduction.mdx' },
+                { name: '02-example-record.mdx' },
+              ],
+            },
+          ],
+        },
+        {
+          name: 'runbooks',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            { name: '01-introduction.mdx' },
+            { name: '02-deployment-procedure.mdx' },
+            { name: '03-disaster-recovery.mdx' },
+            { name: '04-incident-response.mdx' },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
 
-In this example we have global documentation for:
+In this example we have high level documentation for:
 
 - architecture Decision Records
 - Runbooks
 
-:::tip Organize your global documentation
+:::tip Organize your high level documentation
 We added numbers (01, 02, 03) to the files to help with maintenance, you can configure the order of the files in your configuration.
 :::
 
 
-#### Structure of markdown files for global documentation
+#### Structure of markdown files for high level documentation
 
 Each markdown file is split into two parts:
 
@@ -203,5 +243,3 @@ export default {
 
 
 
-
-

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

@@ -8,6 +8,10 @@ title: Components
 description: Component list for custom pages 
 ---
 
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+
+<PlanBanner plan="Scale" />
+
 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).
@@ -50,4 +54,3 @@ In custom documentation pages, `id`, `version`, and `type` are all required. A `
 | `search` | boolean | No | Show or hide the search bar. Accepts `true`/`false` or `"true"`/`"false"`. Defaults to `true`. |
 | `legend` | boolean | No | Show or hide the legend. Accepts `true`/`false` or `"true"`/`"false"`. Defaults to `true`. |
 | `mode` | string | No | `"simple"` or `"full"`. Defaults to `"simple"`. |
-

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

@@ -10,8 +10,10 @@ description: Adding owners to custom pages with EventCatalog.
 ---
 
 import AddedIn from '@site/src/components/MDX/AddedIn';
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
 
 <AddedIn version="2.33.0" />
+<PlanBanner plan="Scale" />
 
 Owners in EventCatalog are either **users** or **teams** and are **optional**.
 
@@ -42,4 +44,3 @@ Assigning owners to your custom pages can provide others with context of who own
     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

@@ -1,5 +1,5 @@
 {
-  "label": "Global documentation",
+  "label": "High level documentation",
   "position": 2,
   "collapsible": true,
   "collapsed": true,

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

@@ -0,0 +1,56 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog diagrams
+- Architecture diagrams
+- Custom diagrams
+- Mermaid
+- PlantUML
+- Miro
+- IcePanel
+sidebar_label: What are diagrams?
+title: What are diagrams?
+description: Bring your own diagrams to EventCatalog - version them, compare them, and assign them to any resource
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+You can bring your own diagrams (e.g Miro, DrawIO, Mermaid, PlantUML) into your catalog and assign them to any resource in your catalog.
+
+With diagrams in EventCatalog you can:
+
+- **Bring any diagram type** - Mermaid, PlantUML, Miro embeds, IcePanel, Lucidchart, draw.io, images, or any MDX content
+- **Version and compare your diagrams** - Track how your architecture visualizations evolve over time and compare them
+- **Assign to any resource** - Link to any catalog resource (e.g domain, system, service, message)
+- **Context to your AI** - EventCatalog MCP exposes your diagrams to your AI agents.
+
+<!-- 
+### What do diagrams look like in EventCatalog?
+
+Diagrams have their own dedicated pages with version switching and appear in the sidebar when assigned to resources.
+
+![Diagram page](./img/diagrams.png)
+
+[View Demo of a Target Architecture diagram &rarr;](https://demo.eventcatalog.dev/diagrams/target-architecture/1.0.0)
+
+### When to use custom diagrams
+
+Use diagrams when you want to:
+
+- Document target architecture or migration plans
+- Embed Miro boards, IcePanel views, or other collaborative diagrams
+- Create sequence diagrams showing detailed message flows
+- Share event storming results or architecture decision records
+- Maintain historical versions of architectural diagrams
+- Add visual context that can't be auto-generated from your resources
+
+### Supported content formats
+
+Diagrams support any content you can write in MDX:
+
+- **Mermaid diagrams** - Flowcharts, sequence diagrams, C4 diagrams
+- **PlantUML diagrams** - UML, sequence, component diagrams
+- **Embedded diagrams** - Miro, IcePanel, Lucidchart, draw.io, FigJam
+- **Static images** - PNG, SVG, JPG files
+- **Markdown content** - Add explanations and documentation around visuals
+- **Custom components** - Use any MDX component to enhance your diagrams -->

package/dist/docs/development/bring-your-own-documentation/diagrams/02-creating-diagrams.md

@@ -0,0 +1,262 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog diagrams
+- Creating diagrams
+sidebar_label: Create a diagram
+title: Create a diagram
+description: How to create and organize diagrams in EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PromptBox from '@site/src/components/MDX/PromptBox';
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+EventCatalog Diagrams let's you bring your own diagrams into your Catalog.
+
+![System Architecture diagram](./img/diagrams.png)
+
+## Creating a diagram
+
+### Automatic Creation
+
+<PromptBox preview="Create a new EventCatalog diagram">
+Read https://www.eventcatalog.dev/docs/development/bring-your-own-documentation/diagrams/creating-diagrams.md and https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/diagrams.md then help me create a new EventCatalog diagram in my catalog.
+
+Ask me for the diagram name, what it shows, summary, whether it belongs at the root of the catalog or inside a resource, and what diagram format I want to use such as Mermaid, PlantUML, an embedded tool, an image, or markdown. Then create the correct diagrams/{'{Diagram Name}'}/index.mdx, domains/{'{Domain Name}'}/diagrams/{'{Diagram Name}'}/index.mdx, services/{'{Service Name}'}/diagrams/{'{Diagram Name}'}/index.mdx, or another relevant resource-level diagrams/{'{Diagram Name}'}/index.mdx file with frontmatter and starter markdown.
+
+If I want to embed an external diagram, ask for the embed URL and use the correct EventCatalog diagram component if one exists.
+
+If the catalog does not have a relevant resource, put it into the root diagrams folder.
+
+You can use MDX components found here https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/components.md
+</PromptBox>
+
+Copy this prompt and paste it into your coding agent. Your agent can help you choose where the diagram should live, create the right folder structure, and add the first version of the diagram documentation.
+
+### Manual Creation
+
+Diagrams live in a `diagrams` folder. EventCatalog discovers any `index.mdx` file inside a `diagrams` directory, regardless of where that directory lives in your catalog.
+
+You can place diagrams:
+
+At the root of your catalog:
+
+<ProjectTree
+  items={[
+    {
+      name: 'diagrams',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'system-overview',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+  ]}
+/>
+
+Inside a domain:
+
+<ProjectTree
+  items={[
+    {
+      name: 'domains',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'E-Commerce',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'diagrams',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'target-architecture',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+Inside a service:
+
+<ProjectTree
+  items={[
+    {
+      name: 'services',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'OrderService',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'diagrams',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'api-flow',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+:::tip
+Organize diagrams close to where they're most relevant. System-wide diagrams can be placed at the root level, while resource-specific diagrams should live within that resource's folder.
+:::
+
+## Create the diagram file
+
+Create an `index.mdx` file for the diagram.
+
+Here is an example of a system architecture diagram:
+
+```md title="/diagrams/system-overview/index.mdx (example)"
+---
+id: system-overview
+name: System Overview
+version: 1.0.0
+summary: High-level architecture showing all microservices and their interactions
+---
+
+## System Architecture
+
+This diagram shows our microservices architecture:
+
+\`\`\`mermaid
+graph TB
+    subgraph "Frontend"
+        WebApp[Web Application]
+        MobileApp[Mobile App]
+    end
+
+    subgraph "Backend Services"
+        Gateway[API Gateway]
+        OrderService[Order Service]
+        PaymentService[Payment Service]
+        InventoryService[Inventory Service]
+    end
+
+    subgraph "Data Layer"
+        OrderDB[(Orders DB)]
+        PaymentDB[(Payments DB)]
+        Kafka[Event Stream]
+    end
+
+    WebApp --> Gateway
+    MobileApp --> Gateway
+    Gateway --> OrderService
+    Gateway --> PaymentService
+    OrderService --> Kafka
+    PaymentService --> Kafka
+    OrderService --> OrderDB
+    PaymentService --> PaymentDB
+\`\`\`
+
+### Key Components
+
+- **API Gateway**: Single entry point for all client requests
+- **Order Service**: Handles order creation and management
+- **Payment Service**: Processes payments and refunds
+- **Event Stream**: Kafka for asynchronous communication
+```
+
+
+### Example with PlantUML
+
+```md title="/diagrams/order-flow/index.mdx (example)"
+---
+id: order-flow
+name: Order Processing Flow
+version: 1.0.0
+summary: Sequence diagram showing the complete order processing flow
+---
+
+\`\`\`plantuml
+@startuml
+actor Customer
+participant "Order Service" as Order
+participant "Payment Service" as Payment
+participant "Inventory Service" as Inventory
+
+Customer -> Order: Create Order
+Order -> Inventory: Check Stock
+Inventory --> Order: Stock Available
+Order -> Payment: Process Payment
+Payment --> Order: Payment Confirmed
+Order --> Customer: Order Confirmed
+@enduml
+\`\`\`
+
+## Order Processing Flow
+
+This sequence diagram illustrates the order processing workflow:
+
+1. Customer initiates order creation
+2. Order service validates inventory availability
+3. Payment is processed
+4. Order confirmation is sent to customer
+```
+
+### Example with embedded diagram
+
+EventCatalog provides built-in components to embed diagrams from popular tools like Miro, IcePanel, Lucidchart, draw.io, and FigJam. This lets you bring your existing collaborative diagrams directly into your catalog.
+
+```md title="/diagrams/architecture-overview/index.mdx (example)"
+---
+id: architecture-overview
+name: Architecture Overview
+version: 1.0.0
+summary: Miro board showing our system architecture and design decisions
+---
+
+<Miro embedUrl="https://miro.com/app/board/..." />
+
+## Architecture Overview
+
+This Miro board captures our architecture decisions and system design.
+Key areas covered:
+
+- System context
+- Container architecture
+- Component relationships
+- Technology choices
+```
+
+:::tip
+Check out the [Diagrams documentation](/docs/components/diagram-syntax) to see all available diagram syntax and embed components including `<Miro>`, `<IcePanel>`, `<Lucid>`, `<DrawIO>`, and `<FigJam>`.
+:::
+
+## Next steps
+
+Once you've created diagrams, you can:
+
+- [Reference them from resources](/docs/development/bring-your-own-documentation/diagrams/referencing-diagrams) like domains, services, and messages
+- [Compare diagram versions](/docs/development/bring-your-own-documentation/diagrams/comparing-diagrams) side-by-side

package/dist/docs/development/{guides → bring-your-own-documentation}/diagrams/03-referencing-diagrams.md

@@ -3,18 +3,12 @@ sidebar_position: 3
 keywords:
 - EventCatalog diagrams
 - Referencing diagrams
-sidebar_label: Referencing diagrams
-title: Referencing diagrams from resources
+sidebar_label: Add diagrams to resources
+title: Add diagrams to resources
 description: How to link diagrams to domains, services, messages, and other resources
 ---
 
-import AddedIn from '@site/src/components/MDX/AddedIn';
-
-<AddedIn version="3.3.0" />
-
-One of the key benefits of diagrams in EventCatalog is that they can be referenced from multiple resources. This allows you to create reusable visual documentation that appears in the sidebar of your domains, services, messages, and containers.
-
-## How diagram references work
+You can assign your diagrams to resources in EventCatalog.
 
 When you reference a diagram from a resource, EventCatalog automatically:
 
@@ -107,74 +101,6 @@ diagrams:
 This event is published when...
 ```
 
-### Referencing diagrams from a container
-
-Container-level diagrams often illustrate data models, schema relationships, or access patterns.
-
-```md title="/containers/OrdersDatabase/index.mdx"
----
-id: OrdersDatabase
-name: Orders Database
-version: 1.0.0
-container_type: database
-technology: PostgreSQL 14
-diagrams:
-  - id: orders-schema-diagram
-    version: 1.0.0
-  - id: data-access-patterns
-    version: 1.0.0
----
-
-## Database Overview
-
-The Orders database stores...
-```
-
-## Diagram versioning in references
-
-You can reference specific versions of diagrams or use `latest` to always point to the most recent version:
-
-```yaml
-diagrams:
-  # Reference a specific version
-  - id: system-architecture
-    version: 2.1.0
-
-  # Reference the latest version (default if version is omitted)
-  - id: api-flow
-    version: latest
-
-  # Version field is optional - defaults to latest
-  - id: sequence-diagram
-```
-
-:::tip
-Use specific versions when you want to preserve historical accuracy (e.g., showing the architecture as it was at that resource version). Use `latest` when the diagram is continuously updated and you always want to show the current state.
-:::
-
-## Organizing diagram references
-
-For resources with multiple diagrams, organize them logically:
-
-```yaml
-diagrams:
-  # High-level overviews first
-  - id: domain-context
-    version: 1.0.0
-
-  # Detailed flows second
-  - id: checkout-flow
-    version: 2.0.0
-  - id: payment-flow
-    version: 2.0.0
-
-  # Implementation details last
-  - id: database-schema
-    version: 1.5.0
-```
-
-The diagrams will appear in the sidebar in the order you list them.
-
 ## Viewing referenced diagrams
 
 When viewing a resource that references diagrams, users will see:
@@ -183,13 +109,3 @@ When viewing a resource that references diagrams, users will see:
 2. Each diagram listed with its name
 3. Clicking a diagram navigates to the full diagram page
 4. The diagram page includes version selection and full content
-
-## Diagram reusability
-
-The same diagram can be referenced from multiple resources. For example, a "System Context" diagram might be referenced from:
-
-- The main domain
-- Multiple services within that domain
-- The architecture documentation
-
-This reusability ensures consistency and reduces duplication while allowing teams to organize documentation in the way that makes most sense for their use case.