@eventcatalog/core 4.8.4 → 4.10.0

package/eventcatalog/src/stores/sidebar-store/state.ts

@@ -1,4 +1,5 @@
 import { getCollection } from 'astro:content';
+import { getSidebarForResource, indexSidebarsByFolder } from './custom-sidebar';
 import type { CollectionEntry } from 'astro:content';
 import { getAgents } from '@utils/collections/agents';
 import { getAdrAliasNodeKey, getAdrNodeKey, getAdrs, type Adr } from '@utils/collections/adrs';
@@ -40,7 +41,7 @@ import {
   shouldRenderSideBarSection,
   withArchitectureDecisionsSection,
 } from './builders/shared';
-import { isArchitectureGraphEnabled, isChangelogEnabled } from '@utils/feature';
+import { isArchitectureGraphEnabled, isChangelogEnabled, isResourceDocsEnabled } from '@utils/feature';
 
 export type { NavigationData, NavNode, ChildRef };
 
@@ -296,6 +297,7 @@ export const getNestedSideBarData = async (): Promise<NavigationData> => {
     ubiquitousLanguages,
     resourceDocs,
     resourceDocCategories,
+    customSidebarEntries,
   ] = await Promise.all([
     getDomains({ getAllVersions: false, includeServicesInSubdomains: false }),
     getSystems({ getAllVersions: false }),
@@ -316,8 +318,12 @@ export const getNestedSideBarData = async (): Promise<NavigationData> => {
     getCollection('ubiquitousLanguages'),
     getResourceDocs(),
     getResourceDocCategories(),
+    getCollection('sidebars'),
   ]);
 
+  // Optional per-resource `sidebar.json` overrides, keyed by the folder they sit in.
+  const customSidebars = indexSidebarsByFolder(customSidebarEntries);
+
   // Calculate derived lists to avoid extra fetches
   const allSubDomainIds = new Set(domains.flatMap((d) => (d.data.domains || []).map((sd: any) => sd.data.id)));
   const rootDomains = domains.filter((d) => !allSubDomainIds.has(d.data.id));
@@ -328,6 +334,7 @@ export const getNestedSideBarData = async (): Promise<NavigationData> => {
   const messages = [...allEvents, ...allCommands, ...allQueries];
 
   const context = {
+    resourceDocsEnabled: isResourceDocsEnabled(),
     agents,
     services,
     domains,
@@ -433,11 +440,14 @@ export const getNestedSideBarData = async (): Promise<NavigationData> => {
 
   const flowNodes = flows.reduce(
     (acc, flow) => {
-      acc[`flow:${flow.data.id}:${flow.data.version}`] = withArchitectureDecisionsSection(
-        buildFlowNode(flow, context),
-        flow,
-        adrs
-      );
+      const sidebar = getSidebarForResource(customSidebars, flow);
+      const node = buildFlowNode(flow, context, { sidebar });
+      const versionedKey = `flow:${flow.data.id}:${flow.data.version}`;
+      acc[versionedKey] = sidebar ? node : withArchitectureDecisionsSection(node, flow, adrs);
+      if (flow.data.latestVersion === flow.data.version) {
+        // Store reference to versioned key instead of duplicating the full node
+        acc[`flow:${flow.data.id}`] = versionedKey;
+      }
       return acc;
     },
     {} as Record<string, NavNode>
@@ -446,7 +456,10 @@ export const getNestedSideBarData = async (): Promise<NavigationData> => {
   const domainNodes = domainsWithOwners.reduce(
     (acc, { domain, owners }) => {
       const versionedKey = `domain:${domain.data.id}:${domain.data.version}`;
-      acc[versionedKey] = withArchitectureDecisionsSection(buildDomainNode(domain, owners, context), domain, adrs);
+      const sidebar = getSidebarForResource(customSidebars, domain);
+      const domainNode = buildDomainNode(domain, owners, context, { sidebar });
+      // A custom sidebar decides for itself whether (and where) `$decision-records` renders.
+      acc[versionedKey] = sidebar ? domainNode : withArchitectureDecisionsSection(domainNode, domain, adrs);
       if (domain.data.latestVersion === domain.data.version) {
         // Store reference to versioned key instead of duplicating the full node
         acc[`domain:${domain.data.id}`] = versionedKey;
@@ -538,11 +551,9 @@ export const getNestedSideBarData = async (): Promise<NavigationData> => {
     (acc, { agent, owners }) => {
       const versionedKey = `agent:${agent.data.id}:${agent.data.version}`;
       const agentChannels = agentChannelsMap.get(`${agent.data.id}:${agent.data.version}`) || [];
-      acc[versionedKey] = withArchitectureDecisionsSection(
-        buildAgentNode(agent, owners, context, agentChannels, flowRefsByAgent.get(versionedKey) || []),
-        agent,
-        adrs
-      );
+      const sidebar = getSidebarForResource(customSidebars, agent);
+      const node = buildAgentNode(agent, owners, context, agentChannels, flowRefsByAgent.get(versionedKey) || [], { sidebar });
+      acc[versionedKey] = sidebar ? node : withArchitectureDecisionsSection(node, agent, adrs);
       if (agent.data.latestVersion === agent.data.version) {
         acc[`agent:${agent.data.id}`] = versionedKey;
       }
@@ -555,11 +566,11 @@ export const getNestedSideBarData = async (): Promise<NavigationData> => {
     (acc, { service, owners }) => {
       const versionedKey = `service:${service.data.id}:${service.data.version}`;
       const serviceChannels = serviceChannelsMap.get(`${service.data.id}:${service.data.version}`) || [];
-      acc[versionedKey] = withArchitectureDecisionsSection(
-        buildServiceNode(service, owners, context, serviceChannels, flowRefsByService.get(versionedKey) || []),
-        service,
-        adrs
-      );
+      const sidebar = getSidebarForResource(customSidebars, service);
+      const node = buildServiceNode(service, owners, context, serviceChannels, flowRefsByService.get(versionedKey) || [], {
+        sidebar,
+      });
+      acc[versionedKey] = sidebar ? node : withArchitectureDecisionsSection(node, service, adrs);
       if (service.data.latestVersion === service.data.version) {
         // Store reference to versioned key instead of duplicating the full node
         acc[`service:${service.data.id}`] = versionedKey;
@@ -612,14 +623,17 @@ export const getNestedSideBarData = async (): Promise<NavigationData> => {
       const hasFieldUsage = messagesWithFieldUsage.has(message.data.id);
       const triggers = getTriggersOfMessage(messageReceivers, message, messages);
       const triggeredBy = getTriggeredByOfMessage(messageReceivers, message, messages);
-      acc[versionedKey] = withArchitectureDecisionsSection(
-        buildMessageNode(message, owners, context, hasFieldUsage, flowRefsByMessage.get(versionedKey) || [], {
-          triggers,
-          triggeredBy,
-        }),
+      const sidebar = getSidebarForResource(customSidebars, message);
+      const node = buildMessageNode(
         message,
-        adrs
+        owners,
+        context,
+        hasFieldUsage,
+        flowRefsByMessage.get(versionedKey) || [],
+        { triggers, triggeredBy },
+        { sidebar }
       );
+      acc[versionedKey] = sidebar ? node : withArchitectureDecisionsSection(node, message, adrs);
       if (message.data.latestVersion === message.data.version) {
         // Store reference to versioned key instead of duplicating the full node
         acc[`${type}:${message.data.id}`] = versionedKey;
@@ -634,11 +648,9 @@ export const getNestedSideBarData = async (): Promise<NavigationData> => {
   const containerNodes = containerWithOwners.reduce(
     (acc, { container, owners }) => {
       const versionedKey = `container:${container.data.id}:${container.data.version}`;
-      acc[versionedKey] = withArchitectureDecisionsSection(
-        buildContainerNode(container, owners, context, flowRefsByContainer.get(versionedKey) || []),
-        container,
-        adrs
-      );
+      const sidebar = getSidebarForResource(customSidebars, container);
+      const node = buildContainerNode(container, owners, context, flowRefsByContainer.get(versionedKey) || [], { sidebar });
+      acc[versionedKey] = sidebar ? node : withArchitectureDecisionsSection(node, container, adrs);
       if (container.data.latestVersion === container.data.version) {
         // Store reference to versioned key instead of duplicating the full node
         acc[`container:${container.data.id}`] = versionedKey;
@@ -651,7 +663,9 @@ export const getNestedSideBarData = async (): Promise<NavigationData> => {
   const systemNodes = systemWithOwners.reduce(
     (acc, { system, owners }) => {
       const versionedKey = `system:${system.data.id}:${system.data.version}`;
-      acc[versionedKey] = withArchitectureDecisionsSection(buildSystemNode(system, owners, context), system, adrs);
+      const sidebar = getSidebarForResource(customSidebars, system);
+      const node = buildSystemNode(system, owners, context, { sidebar });
+      acc[versionedKey] = sidebar ? node : withArchitectureDecisionsSection(node, system, adrs);
       if (system.data.latestVersion === system.data.version) {
         // Store reference to versioned key instead of duplicating the full node
         acc[`system:${system.data.id}`] = versionedKey;
@@ -670,12 +684,24 @@ export const getNestedSideBarData = async (): Promise<NavigationData> => {
   );
 
   const dataProductContext = {
+    resourceDocsEnabled: isResourceDocsEnabled(),
     events,
     commands,
     queries,
     services,
     containers,
     channels,
+    adrs,
+    // Included so data-product sidebar.json files resolve the same refs as every other
+    // resource (cross-resource specs, schema-existence checks, latest-only pins).
+    domains,
+    systems,
+    agents,
+    flows,
+    entities,
+    dataProducts,
+    diagrams,
+    schemas,
     resourceDocs,
     resourceDocCategories,
   };
@@ -685,11 +711,11 @@ export const getNestedSideBarData = async (): Promise<NavigationData> => {
   const dataProductNodes = dataProductWithOwners.reduce(
     (acc, { dataProduct, owners }) => {
       const versionedKey = `data-product:${dataProduct.data.id}:${dataProduct.data.version}`;
-      acc[versionedKey] = withArchitectureDecisionsSection(
-        buildDataProductNode(dataProduct, owners, dataProductContext, flowRefsByDataProduct.get(versionedKey) || []),
-        dataProduct,
-        adrs
-      );
+      const sidebar = getSidebarForResource(customSidebars, dataProduct);
+      const node = buildDataProductNode(dataProduct, owners, dataProductContext, flowRefsByDataProduct.get(versionedKey) || [], {
+        sidebar,
+      });
+      acc[versionedKey] = sidebar ? node : withArchitectureDecisionsSection(node, dataProduct, adrs);
       if (dataProduct.data.latestVersion === dataProduct.data.version) {
         acc[`data-product:${dataProduct.data.id}`] = versionedKey;
       }
@@ -701,7 +727,9 @@ export const getNestedSideBarData = async (): Promise<NavigationData> => {
   const adrNodes = adrsWithOwners.reduce(
     (acc, { adr, owners, decisionMakers }) => {
       const versionedKey = getAdrNodeKey(adr);
-      acc[versionedKey] = buildAdrNode(adr, owners, decisionMakers, context);
+      acc[versionedKey] = buildAdrNode(adr, owners, decisionMakers, context, {
+        sidebar: getSidebarForResource(customSidebars, adr),
+      });
       if (adr.data.latestVersion === adr.data.version) {
         acc[getAdrAliasNodeKey(adr)] = versionedKey;
       }
@@ -713,7 +741,9 @@ export const getNestedSideBarData = async (): Promise<NavigationData> => {
   const entityNodes = entitiesWithOwners.reduce(
     (acc, { entity, owners }) => {
       const versionedKey = `entity:${entity.data.id}:${entity.data.version}`;
-      acc[versionedKey] = withArchitectureDecisionsSection(buildEntityNode(entity, owners, context), entity, adrs);
+      const sidebar = getSidebarForResource(customSidebars, entity);
+      const node = buildEntityNode(entity, owners, context, { sidebar });
+      acc[versionedKey] = sidebar ? node : withArchitectureDecisionsSection(node, entity, adrs);
       if (entity.data.latestVersion === entity.data.version) {
         acc[`entity:${entity.data.id}`] = versionedKey;
       }

package/eventcatalog/src/stores/theme-store.ts

@@ -4,11 +4,14 @@ const THEME_KEY = 'eventcatalog-theme';
 
 export type Theme = 'light' | 'dark';
 
-export const themeStore = atom<Theme>('dark');
+// Default theme when the user has not explicitly chosen one. This is also the value the
+// store holds during server rendering, so SSR-safe hooks must hydrate against it.
+export const DEFAULT_THEME: Theme = 'dark';
+
+export const themeStore = atom<Theme>(DEFAULT_THEME);
 
-// Default theme when the user has not explicitly chosen one.
 const getDefaultTheme = (): Theme => {
-  return 'dark';
+  return DEFAULT_THEME;
 };
 
 // Apply theme to document via data-theme attribute

package/eventcatalog/src/styles/tailwind.css

@@ -20,6 +20,88 @@
   font-weight: 400;
 }
 
+/*
+ * Docs typography scale.
+ *
+ * Tailwind Typography's defaults are tuned for long-form articles: 1.75 line-height,
+ * paragraph gaps of 1.25em and heading gaps of 2em. Reference documentation (Stripe,
+ * GitHub, Vercel, Mintlify) measures at ~1.6 line-height, 1em paragraph gaps and heading
+ * gaps of ~1.5em with 500–600 weight headings. Tighten to match so pages read as reference
+ * material rather than essays.
+ *
+ * Scoped to `.docs-layout` (resource, resource-doc, resources, language pages) and
+ * `.custom-docs-shell` (custom documentation) so other
+ * prose surfaces — chat panel, admonitions on custom pages, the homepage — keep the plugin
+ * defaults. These rules are unlayered, so they win over the plugin's `@layer utilities`
+ * output regardless of source order; `h2 + *` etc. are restated because the plugin's
+ * zero-specificity `:where()` versions would otherwise lose to the rules above them.
+ */
+.docs-layout .prose,
+.custom-docs-shell .prose {
+  line-height: 1.6;
+}
+
+.docs-layout .prose p,
+.custom-docs-shell .prose p,
+.docs-layout .prose ul,
+.custom-docs-shell .prose ul,
+.docs-layout .prose ol,
+.custom-docs-shell .prose ol,
+.docs-layout .prose blockquote,
+.custom-docs-shell .prose blockquote,
+.docs-layout .prose table,
+.custom-docs-shell .prose table {
+  margin-top: 1em;
+  margin-bottom: 1em;
+}
+
+.docs-layout .prose li,
+.custom-docs-shell .prose li {
+  margin-top: 0.25em;
+  margin-bottom: 0.25em;
+}
+
+.docs-layout .prose h2,
+.custom-docs-shell .prose h2 {
+  font-weight: 600;
+  letter-spacing: -0.01em;
+  margin-top: 1.6em;
+  margin-bottom: 0.6em;
+}
+
+.docs-layout .prose h3,
+.custom-docs-shell .prose h3 {
+  font-weight: 600;
+  margin-top: 1.5em;
+  margin-bottom: 0.5em;
+}
+
+.docs-layout .prose h4,
+.custom-docs-shell .prose h4 {
+  font-weight: 600;
+  margin-top: 1.4em;
+  margin-bottom: 0.4em;
+}
+
+.docs-layout .prose h2 + *,
+.custom-docs-shell .prose h2 + *,
+.docs-layout .prose h3 + *,
+.custom-docs-shell .prose h3 + *,
+.docs-layout .prose h4 + *,
+.custom-docs-shell .prose h4 + * {
+  margin-top: 0;
+}
+
+.docs-layout .prose > :first-child,
+.custom-docs-shell .prose > :first-child {
+  margin-top: 0;
+}
+
+.docs-layout .prose > :last-child,
+.custom-docs-shell .prose > :last-child {
+  margin-bottom: 0;
+}
+
 /* Dark mode uses data-theme attribute, not prefers-color-scheme */
 @custom-variant dark (&:where([data-theme=dark], [data-theme=dark] *));
 

package/eventcatalog/src/utils/collections/resource-docs.ts

@@ -6,6 +6,7 @@ export {
   getResourceDocCategoriesForResource,
   getResourceDocsForResource,
   getGroupedResourceDocsByType,
+  getResourceDocTypeLabel,
   type ResourceCollection,
   type ResourceDocEntry,
   type ResourceDocCategoryEntry,

package/eventcatalog/src/utils/collections/schema-loader.ts

@@ -76,7 +76,7 @@ export type MessageSchemaResource = {
   default?: boolean;
   latest?: boolean;
   message: {
-    collection: MessageCollection;
+    collectionName: MessageCollection;
     id: string;
     name?: string;
     version: string;
@@ -131,8 +131,10 @@ const getSchemaFormat = (schemaPath: string) => {
   return extension || 'unknown';
 };
 
-const buildGeneratedSchemaId = (message: { collection: MessageCollection; id: string; version: string }, schemaPath: string) =>
-  `schema:${message.collection}:${message.id}:${message.version}:${schemaPath}`;
+const buildGeneratedSchemaId = (
+  message: { collectionName: MessageCollection; id: string; version: string },
+  schemaPath: string
+) => `schema:${message.collectionName}:${message.id}:${message.version}:${schemaPath}`;
 
 const getSchemaCollectionId = ({
   message,
@@ -140,7 +142,7 @@ const getSchemaCollectionId = ({
   schemaRef,
   schemaFile,
 }: {
-  message: { collection: MessageCollection; id: string; version: string };
+  message: { collectionName: MessageCollection; id: string; version: string };
   reference: SchemaReference;
   schemaRef?: string;
   schemaFile?: string;
@@ -249,7 +251,7 @@ const buildSchemaSourceErrorMessage = ({
   source: SchemaSource;
   error: unknown;
 }) => {
-  const messageType = getMessageTypeLabel(schema.message.collection);
+  const messageType = getMessageTypeLabel(schema.message.collectionName);
 
   return [
     '',
@@ -268,7 +270,7 @@ const buildSchemaSourceErrorMessage = ({
 const addLatestMetadata = (schemas: MessageSchemaResource[]) => {
   const schemasByMessage = schemas.reduce(
     (acc, schema) => {
-      const key = `${schema.message.collection}:${schema.message.id}`;
+      const key = `${schema.message.collectionName}:${schema.message.id}`;
       acc[key] = [...(acc[key] ?? []), schema];
       return acc;
     },
@@ -284,7 +286,7 @@ const addLatestMetadata = (schemas: MessageSchemaResource[]) => {
   );
 
   return schemas.map((schema) => {
-    const key = `${schema.message.collection}:${schema.message.id}`;
+    const key = `${schema.message.collectionName}:${schema.message.id}`;
     return {
       ...schema,
       latest: schema.message.version === latestVersionsByMessage[key],
@@ -304,7 +306,7 @@ export const getMessageSchemasFromFrontmatter = ({
   if (!data.id || !data.version) return [];
 
   const message = {
-    collection,
+    collectionName: collection,
     id: data.id,
     name: data.name,
     version: data.version,

package/package.json

@@ -7,7 +7,7 @@
   },
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
-  "version": "4.8.4",
+  "version": "4.10.0",
   "publishConfig": {
     "access": "public"
   },
@@ -119,7 +119,7 @@
     "update-notifier": "^7.3.1",
     "uuid": "^11.1.1",
     "zod": "^4.3.6",
-    "@eventcatalog/linter": "1.1.16",
+    "@eventcatalog/linter": "1.1.17",
     "@eventcatalog/sdk": "2.28.1",
     "@eventcatalog/visualiser": "^4.1.3"
   },
@@ -144,6 +144,7 @@
     "@types/shelljs": "^0.8.15",
     "@types/update-notifier": "^6.0.8",
     "@types/uuid": "^10.0.0",
+    "jsdom": "27.0.0",
     "prettier": "^3.3.3",
     "prettier-plugin-astro": "^0.14.1",
     "tsup": "^8.1.0",