@eventcatalog/core 4.1.3 → 4.1.5

package/dist/docs/development/customization/03-application-sidebar.md

@@ -0,0 +1,246 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog application sidebar
+sidebar_label: Application sidebar
+title: Application Sidebar
+description: Pick and customize the application sidebar.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+The application sidebar is the vertical sidebar that is rendered on every page in EventCatalog.
+
+![Example](../guides/img/custom-sidebars/application-sidebar.png)
+
+### Customize the application sidebar
+
+You can customize the application sidebar with the `navigation.groups` property in your `eventcatalog.config.js` file.
+
+Use this when you want to:
+
+- Reorder the application navigation.
+- Hide built-in navigation items.
+- Add custom links to internal or external pages.
+- Group navigation items under labels.
+- Pin navigation groups to the bottom of the sidebar.
+- Configure which routes make an item active.
+
+:::info Application sidebar vs documentation sidebar
+
+`navigation.groups` customizes the vertical application sidebar.
+
+`navigation.pages` customizes the context-aware documentation sidebar shown on `/docs/*` pages.
+
+:::
+
+If you do not configure `navigation.groups`, EventCatalog renders the default application sidebar.
+
+If you do configure `navigation.groups`, your groups replace the default application sidebar. Add every item you want users to see.
+
+### Built-in navigation items
+
+EventCatalog provides built-in navigation items you can reference by `id`.
+
+| ID | Description |
+| --- | --- |
+| `home` | Home |
+| `docs` | Custom documentation |
+| `catalog` | Discover catalog |
+| `schemas` | Schemas & APIs |
+| `schema-insights` | Schema Insights |
+| `teams` | Teams |
+| `users` | Users |
+| `settings` | Settings |
+
+You can also reference built-in route IDs directly, such as `/schemas/explorer`, `/directory/teams`, or `/settings/general`.
+
+### Group options
+
+Each group in `navigation.groups` supports:
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Unique group identifier. |
+| `label` | `string` | Optional label shown above the group. |
+| `visible` | `boolean` | Set to `false` to hide the group. |
+| `position` | `'top' \| 'bottom'` | Use `bottom` for settings-style groups pinned below the main navigation. Defaults to `top`. |
+| `items` | `array` | Navigation items in this group. |
+
+### Item options
+
+Each item supports:
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Built-in item id, route id, or custom item id. |
+| `label` | `string` | Custom label. Required for custom items. |
+| `icon` | `string` | Any icon exported by [lucide-react](https://lucide.dev/icons/), such as `House`, `BookOpen`, or `LifeBuoy`. |
+| `href` | `string` | Required for custom items. Built-in items provide their own `href`. |
+| `visible` | `boolean` | Set to `false` to hide the item. |
+| `match` | `string \| string[]` | Paths that should mark the item as active. Useful for custom navigation items. |
+
+### Example: default-style navigation
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  navigation: {
+    groups: [
+      {
+        id: 'main',
+        items: [{ id: 'home' }, { id: 'docs' }],
+      },
+      {
+        id: 'browse',
+        label: 'Browse',
+        items: [
+          { id: 'catalog' },
+          { id: 'schemas' },
+          { id: 'schema-insights' },
+        ],
+      },
+      {
+        id: 'organization',
+        label: 'Organization',
+        items: [{ id: 'teams' }, { id: 'users' }],
+      },
+      {
+        id: 'settings',
+        position: 'bottom',
+        items: [{ id: 'settings' }],
+      },
+    ],
+  },
+};
+```
+
+### Hide items
+
+Use `visible: false` to hide a group or item.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  navigation: {
+    groups: [
+      {
+        id: 'browse',
+        label: 'Browse',
+        items: [
+          { id: 'catalog' },
+          { id: 'schemas' },
+          // Hide Schema Insights
+          { id: 'schema-insights', visible: false },
+        ],
+      },
+      {
+        id: 'organization',
+        label: 'Organization',
+        items: [
+          // Hide Teams
+          { id: 'teams', visible: false },
+          { id: 'users' },
+        ],
+      },
+    ],
+  },
+};
+```
+
+### Add custom links
+
+Custom items require an `id`, `label`, `icon`, and `href`.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  navigation: {
+    groups: [
+      {
+        id: 'platform',
+        label: 'Platform',
+        items: [
+          {
+            id: 'platform-docs',
+            label: 'Platform Docs',
+            icon: 'BookOpen',
+            href: '/docs/custom/platform/overview',
+            match: ['/docs/custom/platform'],
+          },
+          {
+            id: 'support',
+            label: 'Support',
+            icon: 'LifeBuoy',
+            href: 'https://support.example.com',
+          },
+        ],
+      },
+    ],
+  },
+};
+```
+
+External `href` values open in a new tab.
+
+### Active route matching
+
+Built-in items know which routes should mark them as active.
+
+For custom links, use `match` when more than one route should activate the same navigation item.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  navigation: {
+    groups: [
+      {
+        id: 'platform',
+        items: [
+          {
+            id: 'platform-docs',
+            label: 'Platform Docs',
+            icon: 'BookOpen',
+            href: '/docs/custom/platform/overview',
+            match: [
+              '/docs/custom/platform',
+              '/docs/custom/engineering-standards',
+            ],
+          },
+        ],
+      },
+    ],
+  },
+};
+```
+
+### Migrating from `sidebar`
+
+In v3 you could show or hide application sidebar items using the top-level `sidebar` property.
+
+In v4 this has been replaced by `navigation.groups`.
+
+```diff title="eventcatalog.config.js"
+module.exports = {
+-  sidebar: [
+-    { id: '/directory/teams', visible: false },
+-    { id: '/schemas/fields', visible: false },
+-  ],
++  navigation: {
++    groups: [
++      {
++        id: 'browse',
++        label: 'Browse',
++        items: [
++          { id: 'catalog' },
++          { id: 'schemas' },
++          { id: 'schema-insights', visible: false },
++        ],
++      },
++      {
++        id: 'organization',
++        label: 'Organization',
++        items: [{ id: 'teams', visible: false }, { id: 'users' }],
++      },
++    ],
++  },
+};
+```
+
+The `SideBarConfig` type is no longer exported.

package/dist/docs/development/customization/03-search.md

@@ -1,12 +1,12 @@
 ---
-sidebar_position: 1
+sidebar_position: 4
 keywords:
   - EventCatalog search
   - full-content search
   - indexed search
   - pagefind
   - search configuration
-sidebar_label: Search
+sidebar_label: Global Search
 title: Search
 description: Configure resource metadata search or opt-in to full-content indexed search
 ---

package/dist/docs/development/customization/{customize-sidebars/01-documentation-sidebar.md → 04-documentation-sidebar.md}

@@ -1,8 +1,8 @@
 ---
-sidebar_position: 1
+sidebar_position: 2
 keywords:
 - EventCatalog documentation sidebar
-sidebar_label: Documentation Sidebar
+sidebar_label: Docs sidebar
 title: Documentation sidebar
 description: Pick and customize the documentation sidebar.
 ---
@@ -13,7 +13,7 @@ The documentation sidebar is a [context aware sidebar](#what-is-context-aware-si
 
 Clicking on any resource in the sidebar will show you related information to that selected resource ([see demo](https://demo.eventcatalog.dev/)).
 
-![](./images/docs-sidebar.png)
+![](./img/docs-sidebar.png)
 
 ## What is a context aware sidebar?
 
@@ -48,7 +48,7 @@ module.exports = {
 };
 ```
 
-![](./images/custom-docs-sidebar.png)
+![](./img/custom-docs-sidebar.png)
 
 #### Available navigation configuration
 

package/dist/docs/development/customization/05-custom-pages-and-api-routes/01-introduction.md

@@ -0,0 +1,94 @@
+---
+sidebar_position: 1
+keywords:
+  - EventCatalog custom pages
+  - EventCatalog API routes
+  - Astro pages
+  - custom routes
+sidebar_label: Introduction
+title: Custom pages and API routes
+description: Understand custom pages and API routes in EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+
+<AddedIn version="4.1.1" />
+<PlanBanner plan="Scale" />
+
+EventCatalog gives you a structured catalog out of the box, but every organization eventually needs pages that are specific to how they work.
+
+Custom pages and API routes let you extend EventCatalog beyond the built-in catalog views. You can create any page you need, reuse your own components, keep pages static when the content is simple, or connect pages to other systems when you need live data.
+
+Use this when you want EventCatalog to become the place for catalog-specific tools and experiences, such as:
+
+- Internal reports and dashboards.
+- Team onboarding pages.
+- Architecture review workflows.
+- Scorecards and ownership views.
+- Lightweight API routes for catalog data.
+- Pages that combine EventCatalog resources with data from systems such as service catalogs, deployment platforms, observability tools, or internal APIs.
+
+## What are custom pages?
+
+Custom pages are `.astro` files that EventCatalog turns into routes in your generated catalog.
+
+For example, `pages/reports.astro` becomes `/custom/reports` by default.
+
+Custom pages are useful when markdown is not enough. Use them when you need layout control, custom components, conditional rendering, or a small internal tool that belongs inside the catalog.
+
+They can be static pages built entirely from catalog data, or pages that call API routes and other systems to show live information.
+
+## What are API routes?
+
+API routes are server endpoints that live in `pages/api`.
+
+For example, `pages/api/services.ts` becomes `/custom/api/services` by default.
+
+API routes are useful when you want to expose catalog data, receive form submissions, power a custom page, or connect a catalog workflow to another internal system.
+
+For example, a custom page could show service ownership from EventCatalog, deployment status from your platform, and incidents from your observability tool in one view.
+
+## Custom pages, custom docs, and custom components
+
+EventCatalog has a few customization features. Pick the smallest one that fits the job.
+
+| Feature | Use it when |
+| --- | --- |
+| [Custom documentation](/docs/development/bring-your-own-documentation/custom-pages/introduction) | You want markdown documentation under `/docs/custom`. |
+| [Custom components](/docs/development/components/custom-components/introduction) | You want reusable UI inside markdown or MDX pages. |
+| [Custom homepage](/docs/development/customization/customize-landing-page) | You want to replace the catalog homepage at `/`. |
+| Custom pages | You want new catalog routes with custom Astro code. |
+| API routes | You want server endpoints inside the catalog. |
+
+:::info Custom homepage
+
+`pages/homepage.astro` is still the way to customize the catalog homepage. That file is rendered at `/` and is not served under the custom pages prefix.
+
+This section covers additional custom pages and API routes.
+
+:::
+
+## How routing works
+
+EventCatalog uses [Astro](https://astro.build/) under the hood. Files in your catalog's top-level `pages` directory become routes in your generated catalog.
+
+By default, custom pages are served under `/custom`. You can change this prefix.
+
+| File | Route |
+| --- | --- |
+| `pages/reports.astro` | `/custom/reports` |
+| `pages/reports/index.astro` | `/custom/reports` |
+| `pages/reports/[id].astro` | `/custom/reports/[id]` |
+| `pages/api/teams.ts` | `/custom/api/teams` |
+| `pages/data.json.ts` | `/custom/data.json` |
+
+EventCatalog supports Astro-style dynamic route segments such as `[id]` and `[...slug]`.
+
+After you create a custom page, you can add it to your catalog navigation by customizing the [application sidebar](/docs/development/customization/application-sidebar).
+
+## Next steps
+
+- [Create a custom page](/docs/development/customization/custom-pages-and-api-routes/create-a-custom-page)
+- [Create an API route](/docs/development/customization/custom-pages-and-api-routes/create-an-api-route)
+- [Routing and configuration reference](/docs/development/customization/custom-pages-and-api-routes/reference)

package/dist/docs/development/customization/05-custom-pages-and-api-routes/02-create-a-custom-page.md

@@ -0,0 +1,177 @@
+---
+sidebar_position: 2
+keywords:
+  - EventCatalog custom pages
+  - Astro page
+  - custom routes
+sidebar_label: Create a custom page
+title: Create a custom page
+description: Add a custom Astro page to your EventCatalog.
+---
+
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+This guide shows you how to add a custom page to your catalog.
+
+Use this when you want a new route for an internal report, dashboard, onboarding page, or catalog-specific workflow. The page can be static, built from catalog data, or use browser-side code to call API routes and other systems.
+
+## Create the page file
+
+Create a top-level `pages` directory and add an `.astro` file.
+
+<ProjectTree
+  items={[
+    {
+      name: 'pages',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        { name: 'reports.astro', highlight: true },
+      ],
+    },
+  ]}
+/>
+
+```js title="pages/reports.astro"
+---
+// Use the EventCatalog layout so your page keeps the catalog header and sidebar.
+import Layout from '@catalog/layouts/Layout.astro';
+
+// Use @catalog/utils to read catalog resources from your custom page.
+import { getServices } from '@catalog/utils';
+
+// getAllVersions: false returns the latest version of each service.
+const services = await getServices({ getAllVersions: false });
+---
+
+<Layout title="Service reports" description="Operational views built from catalog data.">
+  <div class="not-prose space-y-6">
+    <div>
+      <h1 class="text-3xl font-semibold">Service reports</h1>
+      <p class="text-gray-600">There are {services.length} services in this catalog.</p>
+    </div>
+
+    <ul class="grid gap-3 md:grid-cols-2">
+      {services.map((service) => (
+        <li class="rounded-lg border border-gray-200 p-4">
+          <h2 class="font-semibold">{service.data.name}</h2>
+          <p class="text-sm text-gray-600">{service.data.summary}</p>
+        </li>
+      ))}
+    </ul>
+  </div>
+</Layout>
+```
+
+## Run your catalog
+
+Start EventCatalog.
+
+```bash
+npm run dev
+```
+
+Open `/custom/reports`.
+
+## Add the page to your navigation
+
+Custom pages are available by URL as soon as you create them. To make the page easier for users to find, add it to your application sidebar.
+
+Add a custom navigation item in `eventcatalog.config.js`.
+
+```js title="eventcatalog.config.js"
+export default {
+  navigation: {
+    groups: [
+      {
+        id: 'tools',
+        label: 'Tools',
+        items: [
+          {
+            id: 'service-reports',
+            label: 'Service reports',
+            icon: 'ChartBar',
+            href: '/custom/reports',
+            match: ['/custom/reports'],
+          },
+        ],
+      },
+    ],
+  },
+};
+```
+
+The `href` is the custom page route. The `match` value tells EventCatalog when to mark the navigation item as active.
+
+For more navigation options, see [Application sidebar](/docs/development/customization/application-sidebar).
+
+## Add a custom component
+
+You can reuse Astro components from your catalog's top-level `components` directory.
+
+<ProjectTree
+  items={[
+    {
+      name: 'components',
+      type: 'folder',
+      defaultOpen: true,
+      children: [{ name: 'ReportCard.astro', highlight: true }],
+    },
+    {
+      name: 'pages',
+      type: 'folder',
+      defaultOpen: true,
+      children: [{ name: 'reports.astro' }],
+    },
+  ]}
+/>
+
+```js title="components/ReportCard.astro"
+---
+// Props are values passed into this component from the page that renders it.
+const { title, description } = Astro.props;
+---
+
+<article class="rounded-lg border border-gray-200 p-4">
+  <h2 class="font-semibold">{title}</h2>
+  <p class="text-sm text-gray-600">{description}</p>
+</article>
+```
+
+Import the component into your custom page.
+
+```js title="pages/reports.astro"
+---
+import Layout from '@catalog/layouts/Layout.astro';
+
+// Components in your catalog's top-level components directory are available from @catalog/components.
+import ReportCard from '@catalog/components/ReportCard.astro';
+---
+
+<Layout title="Reports">
+  <ReportCard title="Service health" description="Operational view for catalog services." />
+</Layout>
+```
+
+## Add a dynamic page
+
+Use Astro dynamic route segments when the route needs a parameter.
+
+```js title="pages/reports/[id].astro"
+---
+import Layout from '@catalog/layouts/Layout.astro';
+
+// Dynamic route parameters come from the filename. Here, [id].astro provides Astro.params.id.
+const { id } = Astro.params;
+---
+
+<Layout title={`Report: ${id}`}>
+  <h1>Report: {id}</h1>
+</Layout>
+```
+
+This page is available at `/custom/reports/:id`, for example `/custom/reports/orders`.
+
+## Learn more
+
+Custom pages follow Astro's routing model. See the [Astro pages documentation](https://docs.astro.build/en/basics/astro-pages/) if you want to go deeper.

package/dist/docs/development/customization/05-custom-pages-and-api-routes/03-create-an-api-route.md

@@ -0,0 +1,128 @@
+---
+sidebar_position: 3
+keywords:
+  - EventCatalog API routes
+  - Astro endpoints
+  - server mode
+sidebar_label: Create an API route
+title: Create an API route
+description: Add a custom API route to your EventCatalog.
+---
+
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+This guide shows you how to add a custom API route to your catalog.
+
+Use this when you want to expose catalog data, receive form submissions, or power a custom page with server-side logic. API routes are also useful when a custom page needs data from another internal system and you want that integration to live inside EventCatalog.
+
+## Enable server mode
+
+Custom API routes require EventCatalog to run in server mode when you build the catalog.
+
+Set `output: 'server'` in `eventcatalog.config.js`.
+
+```js title="eventcatalog.config.js"
+export default {
+  output: 'server',
+};
+```
+
+## Create the endpoint file
+
+Create a file inside `pages/api`.
+
+<ProjectTree
+  items={[
+    {
+      name: 'pages',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'api',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'services.ts', highlight: true }],
+        },
+      ],
+    },
+  ]}
+/>
+
+```js title="pages/api/services.ts"
+import type { APIRoute } from 'astro';
+
+// Use @catalog/utils to read catalog resources from your API route.
+import { getServices } from '@catalog/utils';
+
+// Export a function named after the HTTP method this route should handle.
+export const GET: APIRoute = async () => {
+  // getAllVersions: false returns the latest version of each service.
+  const services = await getServices({ getAllVersions: false });
+
+  return Response.json({
+    services: services.map((service) => ({
+      id: service.data.id,
+      name: service.data.name,
+      version: service.data.version,
+    })),
+  });
+};
+```
+
+This route is served at `/custom/api/services`.
+
+## Add another HTTP method
+
+Astro calls exported functions that match the request method, such as `GET`, `POST`, or `DELETE`.
+
+```js title="pages/api/reviews.ts"
+import type { APIRoute } from 'astro';
+
+// This function handles POST requests sent to /custom/api/reviews.
+export const POST: APIRoute = async ({ request }) => {
+  const body = await request.json();
+
+  return Response.json({
+    status: 'received',
+    resource: body.resource,
+  });
+};
+```
+
+This route receives `POST` requests at `/custom/api/reviews`.
+
+## Call an API route from a custom page
+
+You can call your API route from a custom page like any other endpoint.
+
+```js title="pages/reports.astro"
+---
+// Use the EventCatalog layout so your page keeps the catalog header and sidebar.
+import Layout from '@catalog/layouts/Layout.astro';
+---
+
+<Layout title="Reports">
+  <button id="load-services">Load services</button>
+  <pre id="services-output"></pre>
+</Layout>
+
+<script>
+  const button = document.querySelector('#load-services');
+  const output = document.querySelector('#services-output');
+
+  button?.addEventListener('click', async () => {
+    // This calls the custom API route defined in pages/api/services.ts.
+    const response = await fetch('/custom/api/services');
+    const data = await response.json();
+
+    if (output) {
+      output.textContent = JSON.stringify(data, null, 2);
+    }
+  });
+</script>
+```
+
+## Learn more
+
+Custom API routes follow Astro's endpoint model. See the [Astro endpoints documentation](https://docs.astro.build/en/guides/endpoints/) if you want to go deeper.