@eventcatalog/core 3.34.0 → 3.35.1

package/dist/docs/development/authentication/providers/04-setting-up-azure-ad.md

@@ -0,0 +1,100 @@
+---
+sidebar_position: 4
+keywords:
+- EventCatalog components
+sidebar_label: Azure AD (Entra ID)
+title: Setting up Azure AD (Entra ID)
+description: Setting up Microsoft Entra ID authentication for EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+
+<AddedIn version="2.43.1" />
+<PlanBanner plan="Enterprise" />
+
+:::info
+This guide takes your through setting up a protected sign-in screen for your docs. Before going through this guide, make sure you've first gone through [Enabling authentication](/docs/development/authentication/enabling-authentication).
+:::
+
+To setup your EventCatalog site with visitor authentication using [Microsoft Entra ID](https://entra.microsoft.com/) (formerly Azure Active Directory), the process looks as follows:
+
+1. [Create a new Azure app registration](#create-a-new-azure-app-registration)
+2. [Configure the Azure app in EventCatalog](#configure-the-azure-app-in-eventcatalog)
+3. [Test the authentication](#test-the-authentication)
+
+## Create a new Azure app registration
+
+First, you will need to create a new app registration in the Azure portal.
+
+1. Go to [portal.azure.com](https://portal.azure.com) and sign up for a free account or login
+2. Search for **Microsoft Entra ID** (or **Azure Active Directory**) in the top search bar
+3. Navigate to **App registrations** → **New registration**
+4. Fill in the application details:
+  - **Name:** `EventCatalog`
+  - **Supported account types:** Select **Accounts in any organizational directory and personal Microsoft accounts** (for broader compatibility)
+  - **Redirect URI:** Select **Web** and enter:
+    - Local development: `http://localhost:3000/api/auth/callback/microsoft-entra-id`
+5. Click **Register**
+6. After registration, note the **Application (client) ID** and **Directory (tenant) ID** from the Overview page
+7. Navigate to **Certificates & secrets** → **New client secret**
+8. Add a description (e.g., "EventCatalog Secret") and choose an expiration period
+9. Click **Add** and immediately copy the secret **Value** (you won't see it again)
+10. Go to **Authentication** in the sidebar and configure:
+   - Add additional redirect URIs for production: `{YOUR_EVENTCATALOG_SITE_URL}/api/auth/callback/microsoft-entra-id`
+   - Under **Implicit grant and hybrid flows**, check **ID tokens**
+   - Click **Save**
+
+## Configure the Azure app in EventCatalog
+
+Add your Azure AD Client ID, Client Secret, and Tenant ID to your `.env` file.
+
+```env title=".env"
+AUTH_MICROSOFT_ENTRA_ID_ID={YOUR_AZURE_CLIENT_ID}
+AUTH_MICROSOFT_ENTRA_ID_SECRET={YOUR_AZURE_CLIENT_SECRET}
+AUTH_MICROSOFT_ENTRA_ID_ISSUER=https://login.microsoftonline.com/{YOUR_AZURE_TENANT_ID}/v2.0
+```
+
+Your Azure AD tenant ID can be found in your app registration's Overview page in the Azure portal.
+
+In your eventcatalog.auth.js file, add the following:
+
+```js title="eventcatalog.auth.js"
+export default {
+  enabled: true,
+  providers: {
+    entra: {
+      clientId: process.env.AUTH_MICROSOFT_ENTRA_ID_ID,
+      clientSecret: process.env.AUTH_MICROSOFT_ENTRA_ID_SECRET,
+      issuer: process.env.AUTH_MICROSOFT_ENTRA_ID_ISSUER,
+    },
+  },
+};
+```
+
+## Test the authentication
+
+![Okta authentication](./img/microsoft-auth.png)
+
+Restart your EventCatalog server and test the authentication.
+
+```bash
+npm run dev
+```
+
+All pages should now be protected and require a Microsoft account to access.
+
+1. Navigate to your EventCatalog site
+1. You should be redirected to the sign-in page
+1. Click Sign in with Azure AD
+1. You'll be redirected to Microsoft's login page
+1. Enter your Microsoft account credentials (personal or organizational)
+1. After successful authentication, you'll be redirected back to EventCatalog
+
+## Found an issue?
+
+Remember to setup the prerequisites for this guide:
+
+- [Enabling authentication](/docs/development/authentication/enabling-authentication)
+
+If you still have problems, please [let us know](https://github.com/eventcatalog/eventcatalog/issues/new/choose).

package/dist/docs/development/authentication/providers/05-setting-up-okta.md

@@ -0,0 +1,105 @@
+---
+sidebar_position: 5
+keywords:
+- EventCatalog components
+sidebar_label: Okta 
+title: Setting up Okta
+description: Setting up Okta authentication for EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+
+<AddedIn version="2.43.0" />
+<PlanBanner plan="Enterprise" />
+
+:::info
+This guide takes your through setting up a protected sign-in screen for your docs. Before going through this guide, make sure you've first gone through [Enabling authentication](/docs/development/authentication/enabling-authentication).
+:::
+
+To setup your EventCatalog site with visitor authentication using [Okta](https://www.okta.com/), the process looks as follows:
+
+1. Create a new Okta OAuth app
+2. Configure the OAuth app in EventCatalog
+3. Test the authentication
+
+## Create a new Okta OAuth app
+
+First, you will need to create a new Okta OAuth app in your Okta Admin Console.
+
+1. Log in to your **[Okta Admin Console](https://login.okta.com/signin)**
+2. Navigate to **Applications** → **Applications**
+3. Click **Create App Integration**
+4. Select **OIDC - OpenID Connect** as the sign-in method
+5. Select **Web Application** as the application type
+6. Click **Next**
+7. Fill in the application details:
+    - **App integration name:** `EventCatalog`
+    - **Grant types:** Check `Authorization Code`
+    - **Sign-in redirect URIs:** 
+        - Production: `{YOUR_EVENTCATALOG_SITE_URL}/api/auth/callback/okta`
+        - Local development: `http://localhost:3000/api/auth/callback/okta`
+    - **Sign-out redirect URIs:**
+        - Production: `{YOUR_EVENTCATALOG_SITE_URL}`
+        - Local development: `http://localhost:3000`
+8. Under **Assignments**, choose who can access this application:
+    - **Allow everyone in your organization to access** (recommended)
+    - Or assign to specific groups
+9. Click **Save**
+10. Copy the **Client ID** and **Client Secret** from the app settings
+11. Note your **Okta domain** (e.g., `https://your-domain.okta.com`)
+
+## Configure the OAuth app in EventCatalog
+
+Add your Okta Client ID, Client Secret, and Issuer to your `.env` file.
+
+```env title=".env"
+AUTH_OKTA_CLIENT_ID={YOUR_OKTA_CLIENT_ID}
+AUTH_OKTA_CLIENT_SECRET={YOUR_OKTA_CLIENT_SECRET}
+AUTH_OKTA_ISSUER=https://{YOUR_OKTA_DOMAIN}
+```
+
+Your Okta issuer URL should be in the format: https://your-domain.okta.com (without /oauth2/default unless you're using a custom authorization server).
+In your eventcatalog.auth.js file, add the following:
+
+```js title="eventcatalog.auth.js"
+export default {
+  enabled: true,
+  providers: {
+    okta: {
+      clientId: process.env.AUTH_OKTA_CLIENT_ID,
+      clientSecret: process.env.AUTH_OKTA_CLIENT_SECRET,
+      issuer: process.env.AUTH_OKTA_ISSUER,
+    },
+  },
+};
+```
+
+## Test the authentication
+
+![Okta authentication](./img/okta-auth.png)
+
+Restart your EventCatalog server and test the authentication.
+
+```bash
+npm run dev
+```
+
+All pages should now be protected and require an Okta account to access.
+
+1. Navigate to your EventCatalog site
+1. You should be redirected to the sign-in page
+1. Click Sign in with Okta
+1. You'll be redirected to your Okta login page
+1. Enter your Okta credentials
+1. After successful authentication, you'll be redirected back to EventCatalog
+
+
+## Found an issue?
+
+Remember to setup the prerequisites for this guide:
+
+- [Enabling authentication](/docs/development/authentication/enabling-authentication)
+
+If you still have problems, please [let us know](https://github.com/eventcatalog/eventcatalog/issues/new/choose).
+

package/dist/docs/development/authentication/providers/06-setting-up-auth0.md

@@ -0,0 +1,106 @@
+---
+sidebar_position: 6
+keywords:
+- EventCatalog components
+sidebar_label: Auth0 
+title: Setting up Auth0
+description: Setting up Auth0 authentication for EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+
+<AddedIn version="2.43.1" />
+<PlanBanner plan="Enterprise" />
+
+:::info
+This guide takes your through setting up a protected sign-in screen for your docs. Before going through this guide, make sure you've first gone through [Enabling authentication](/docs/development/authentication/enabling-authentication).
+:::
+
+To setup your EventCatalog site with visitor authentication using [Auth0](https://auth0.com/), the process looks as follows:
+
+1. [Create a new Auth0 application](#create-a-new-auth0-application)
+2. [Configure the Auth0 app in EventCatalog](#configure-the-auth0-app-in-eventcatalog)
+3. [Test the authentication](#test-the-authentication)
+
+## Create a new Auth0 application
+
+First, you will need to create a new Auth0 application in your Auth0 Dashboard.
+
+1. Go to [auth0.com](https://auth0.com) and sign up for a free account or login
+2. In the Auth0 Dashboard, navigate to **Applications** → **Applications**
+3. Click **Create Application**
+4. Fill in the application details:
+   - **Name:** `EventCatalog`
+   - **Application Type:** Select **Regular Web Applications**
+5. Click **Create**
+6. In your new application's **Settings** tab, configure the following:
+   - **Allowed Callback URLs:**
+       - Production: `{YOUR_EVENTCATALOG_SITE_URL}/api/auth/callback/auth0`
+       - Local development: `http://localhost:3000/api/auth/callback/auth0`
+   - **Allowed Logout URLs:**
+       - Production: `{YOUR_EVENTCATALOG_SITE_URL}`
+       - Local development: `http://localhost:3000`
+   - **Allowed Web Origins:**
+       - Production: `{YOUR_EVENTCATALOG_SITE_URL}`
+       - Local development: `http://localhost:3000`
+   - **Allowed Origins (CORS):**
+       - Production: `{YOUR_EVENTCATALOG_SITE_URL}`
+       - Local development: `http://localhost:3000`
+7. Leave **Initiate Login URI** empty (not required)
+8. Click **Save Changes**
+9. Copy the **Domain**, **Client ID**, and **Client Secret** from the app settings
+
+## Configure the Auth0 app in EventCatalog
+
+Add your Auth0 Domain, Client ID, and Client Secret to your `.env` file.
+
+```env title=".env"
+AUTH_AUTH0_ID={YOUR_AUTH0_CLIENT_ID}
+AUTH_AUTH0_SECRET={YOUR_AUTH0_CLIENT_SECRET}
+AUTH_AUTH0_ISSUER=https://{YOUR_AUTH0_DOMAIN}
+```
+
+Your Auth0 issuer URL should be in the format: https://your-tenant.auth0.com (this is the Domain from your Auth0 application settings).
+
+In your eventcatalog.auth.js file, add the following:
+
+```js title="eventcatalog.auth.js"
+export default {
+  enabled: true,
+  providers: {
+    auth0: {
+      clientId: process.env.AUTH_AUTH0_ID,
+      clientSecret: process.env.AUTH_AUTH0_SECRET,
+      issuer: process.env.AUTH_AUTH0_ISSUER,
+    },
+  },
+};
+```
+
+## Test the authentication
+
+![Okta authentication](./img/auth0-auth.png)
+
+Restart your EventCatalog server and test the authentication.
+
+```bash
+npm run dev
+```
+
+All pages should now be protected and require an Auth0 account to access.
+
+1. Navigate to your EventCatalog site
+1. You should be redirected to the sign-in page
+1. Click Sign in with Auth0
+1. You'll be redirected to your Auth0 login page
+1. Enter your credentials or sign up for a new account
+1. After successful authentication, you'll be redirected back to EventCatalog
+
+## Found an issue?
+
+Remember to setup the prerequisites for this guide:
+
+- [Enabling authentication](/docs/development/authentication/enabling-authentication)
+
+If you still have problems, please [let us know](https://github.com/eventcatalog/eventcatalog/issues/new/choose).

package/dist/docs/development/authentication/providers/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Providers",
+  "position": 15,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/development/authentication/providers",
+    "description": "Authentication for EventCatalog"
+  }
+}

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

@@ -0,0 +1,48 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog custom documentation
+sidebar_label: Introduction
+title: Bring your own documentation
+description: Bring your own documentation to EventCatalog
+---
+
+EventCatalog allows you to centralise architecture documentation alongside your domains, services, and events — keeping knowledge and context in one place.
+
+Common use cases include:
+
+- Architecture decision records (ADRs)
+- Infrastructure & operations runbooks
+- CI/CD documentation
+- User journeys
+- API documentation
+- Technical debt tracking
+- Team processes
+- Onboarding information
+- Best practices & standards
+
+EventCatalog provides two ways to bring your own documentation to your catalog:
+
+1. [Global documentation](#1-global-documentation) 
+   - for cross-cutting and catalog-wide knowledge
+2. [Resource-level documentation](#2-resource-level-documentation) 
+   - for implementation details tied to a specific resoruce (e.g domain, service, or event)
+
+---
+
+### Global documentation
+
+Global documentation can be used to document cross-cutting and catalog-wide knowledge. 
+You can bring your own documentation to your catalog and have your own documentation section (/docs/custom/) regardless of EventCatalog resources.
+
+[Read the custom pages guide](/docs/guides/bring-your-own-documentation/custom-pages).
+
+### Resource-level documentation
+
+Resource-level documentation can be used to document implementation details tied to a specific EventCatalog resource (e.g domain, service, or event).
+
+This can be useful if you want to document details tied to a specific domain, service, message, data product, etc.
+
+EventCatalog will render your custom documentation alongside the resource it is tied to in the sidebar.
+
+[Read the resource docs guide](/docs/guides/bring-your-own-documentation/resource-docs).

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

@@ -0,0 +1,12 @@
+{
+  "label": "Bring your own documentation",
+  "position": 5,
+  "collapsible": true,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "slug": "bring-your-own-documentation",
+    "title": "Bring your own documentation",
+    "description": "Bring your own documentation to EventCatalog. Add global custom pages or attach docs directly to individual resources."
+  }
+}

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

@@ -0,0 +1,60 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog custom documentation
+sidebar_label: Introduction
+title: Introduction
+description: Customize documentation in EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.33.0" />
+
+<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.
+
+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.
+
+
+![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:
+
+- Document architecture decision records
+- Document infrastructure & operations
+- Document CI/CD pipelines
+- Document user journeys
+- Document API documentation
+- Document technical debt
+- Document team processes
+- Document onboarding information
+- Document best practices
+- Document standards
+
+It's really up to you what you add here.
+
+### How global 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?
+
+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
+
+This is the initial version of global 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)

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

@@ -0,0 +1,207 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog global documentation
+sidebar_label: Adding global documentation
+title: Adding global documentation
+description: Adding global documentation to your EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.33.0" />
+
+## 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.
+
+## Adding global documentation
+
+Global 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/`.
+
+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
+
+```
+
+In this example we have global documentation for:
+
+- architecture Decision Records
+- Runbooks
+
+:::tip Organize your global 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
+
+Each markdown file is split into two parts:
+
+1. The frontmatter (properties at the top of the file)
+2. The content (the rest of the file)
+
+```mdx
+---
+title: Architecture decision records
+summary: A comprehensive guide to creating new microservices at FlowMart following our best practices and standards
+owners: 
+  - dboyne
+badges:
+  - content: 'Guide'
+    backgroundColor: 'teal'
+    textColor: 'teal'
+---
+
+This is your content for your file.
+
+```
+
+**Frontmatter properties**
+
+| Property | Required | Description |
+|----------|----------|-------------|
+| `title` | Yes | The title of the page |
+| `summary` | Yes | A summary of the page |
+| `slug` | No | Ability to override the slug (url) of the page |
+| `owners` | No | Owners of the page (EventCatalog owners) |
+| `badges` | No | The badges of the page |
+
+#### Sidebar configuration
+
+You need to configure the sidebar to include your custom documentation, we do this by using the `customDocs` property in your `eventcatalog.config.js` file.
+
+We have two options for the sidebar:
+
+1. Manually map files and paths to the sidebar
+2. Use the autogenerated option to generate the sidebar items
+
+:::tip Autogenerated sidebar
+The autogenerated sidebar is the easiest option, it will render all the files in the directory and subdirectories.
+If you want to choose which files and order they are displayed in, you can manually map the files and paths to the sidebar.
+:::
+
+```js
+export default {
+  // rest of your config
+  customDocs: {
+    sidebar: [
+      {
+        label: 'architecture Decision Records',
+        badge: {
+          text: 'New', color: 'green'
+        },
+        collapsed: false,
+        items: [
+          {
+            // Here we map the directory, and use autogenerated to generate the sidebar items
+            // Any item added to the folder will be rendered automatically in EventCatalog
+            label: 'Drafts', autogenerated: { directory: '/architecture-decision-records/drafts' }
+          },
+          {
+            label: 'Published', autogenerated: { directory: '/architecture-decision-records/published' }
+          },
+          {
+            label: 'Examples', autogenerated: { directory: '/architecture-decision-records/examples' }
+          }
+        ]
+      },
+      {
+        label: 'Runbooks',
+        badge: {
+          text: 'New', color: 'green'
+        },
+        collapsed: false,
+        items: [
+          {
+            // Here we create custom pages in the sidebar
+            // We can manually map the slug to a file, or use the autogenerated to generate the sidebar items
+            label: 'Creating a new runbook', items: [
+              { label: 'Introduction', slug: 'runbooks/01-introduction' },
+              { label: 'Deployment Procedure', slug: 'runbooks/02-deployment-procedure' },
+              { label: 'Disaster Recovery', slug: 'runbooks/03-disaster-recovery' },
+              { label: 'Incident Response', slug: 'runbooks/04-incident-response' },
+            ]
+          },
+        ]
+      }
+    ]
+  }
+};
+ ```
+
+
+#### Rendered output
+
+The rendered output will be the content of the markdown file, with the frontmatter properties.
+
+![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>
+
+### Custom HTML attributes
+
+<AddedIn version="2.33.4" />
+
+Links can also include an attrs property to add custom HTML attributes to the link element.
+
+In the following example, attrs is used to add a target="_blank" attribute, so that the link opens in a new tab, and to apply a custom style attribute to italicize the link label:
+
+```js
+export default {
+  // rest of your config
+  customDocs: {
+    sidebar: [
+      {
+        label: 'My Links',
+        items: [
+          {
+            label: 'Read more on GitHub',
+            link: 'https://github.com/event-catalog/eventcatalog',
+            attrs: { target: '_blank', style: 'font-style: italic;' },
+          },
+        ]
+      },
+    ]
+  }
+};
+ ```
+
+ #### Rendered output
+
+![Example](./img/custom-attrs.png)
+
+
+
+
+
+
+
+
+
+
+
+