@eventcatalog/core 4.8.4 → 4.10.0

package/eventcatalog/src/content.config.ts

@@ -1179,7 +1179,7 @@ const schemas = defineCollection({
       default: z.boolean().optional(),
       latest: z.boolean().optional(),
       message: z.object({
-        collection: z.enum(['events', 'commands', 'queries']),
+        collectionName: z.enum(['events', 'commands', 'queries']),
         id: z.string(),
         name: z.string().optional(),
         version: z.string(),
@@ -1199,6 +1199,73 @@ const schemas = defineCollection({
     .extend(baseSchema.shape),
 });
 
+// Optional `sidebar.json` next to a resource's index.mdx. When present it fully
+// replaces the generated sidebar for that resource (see stores/sidebar-store/custom-sidebar.ts).
+const sidebarLinkSchema = z
+  .object({
+    title: z.string(),
+    href: z.string(),
+    icon: z.string().optional(),
+  })
+  .strict();
+
+// { "title": "Runbooks", "icon": "Siren", "collapsed": true, "pages": [...] } (custom group).
+// Groups nest: a page can itself be a group, rendered as a subsection.
+type SidebarGroupInput = {
+  title: string;
+  icon?: string;
+  collapsed?: boolean;
+  pages: Array<string | z.input<typeof sidebarLinkSchema> | SidebarGroupInput>;
+};
+const sidebarGroupSchema: z.ZodType<SidebarGroupInput> = z.lazy(() =>
+  z
+    .object({
+      title: z.string(),
+      icon: z.string().optional(),
+      collapsed: z.boolean().optional(),
+      // "$quick-reference", "[[service|OrderService@1.0.0]]", "[[doc|guides/sla]]", { title, href } or a nested group
+      pages: z.array(z.union([z.string(), sidebarLinkSchema, sidebarGroupSchema])),
+    })
+    .strict()
+);
+
+const sidebarSchema = z
+  .object({
+    $schema: z.string().optional(),
+    sections: z.array(
+      z.union([
+        // "$quick-reference" (predefined section)
+        z.string(),
+        // { "section": "$owners", "title": "Team", "collapsed": false } (predefined section, adjusted)
+        z
+          .object({
+            section: z.string(),
+            title: z.string().optional(),
+            icon: z.string().optional(),
+            collapsed: z.boolean().optional(),
+          })
+          .strict(),
+        sidebarGroupSchema,
+      ])
+    ),
+  })
+  .strict();
+
+const sidebars = defineCollection({
+  loader: globWithSafeWatcher({
+    // Anchored to the resource roots (like resourceDocCategories) so an unrelated
+    // sidebar.json elsewhere in the project — or the public/generated mirror — is ignored.
+    pattern: withIgnoredBuildArtifacts(
+      withFederatedContent([
+        '{services,events,commands,queries,flows,containers,channels,entities,data-products,systems,agents,adrs}/**/sidebar.json',
+        'domains/**/sidebar.json',
+      ])
+    ),
+    base: projectDirBase,
+  }),
+  schema: sidebarSchema,
+});
+
 export const collections = {
   events,
   commands,
@@ -1236,4 +1303,7 @@ export const collections = {
 
   // Generated from message schema references
   schemas,
+
+  // Optional per-resource sidebar overrides (sidebar.json)
+  sidebars,
 };

package/eventcatalog/src/enterprise/api/schemas/[collection]/[id]/[version]/index.ts

@@ -11,7 +11,7 @@ import { sortVersioned } from '@utils/collections/util';
 const findSchema = async (collection: string | undefined, id: string, version: string | undefined) => {
   const schemas = await getCollection('schemas');
   const matchingSchemas = schemas.filter(
-    (schema) => schema.data.message.collection === collection && schema.data.message.id === id
+    (schema) => schema.data.message.collectionName === collection && schema.data.message.id === id
   );
 
   if (version === 'latest') {
@@ -30,7 +30,7 @@ export async function getStaticPaths() {
   // Generate paths for specific versions
   const versionedPaths = schemas.map((schema) => ({
     params: {
-      collection: schema.data.message.collection,
+      collection: schema.data.message.collectionName,
       id: schema.data.message.id,
       version: schema.data.message.version,
     },
@@ -45,7 +45,7 @@ export async function getStaticPaths() {
     .filter((schema) => schema.data.latest)
     .map((latestSchema) => ({
       params: {
-        collection: latestSchema.data.message.collection,
+        collection: latestSchema.data.message.collectionName,
         id: latestSchema.data.message.id,
         version: 'latest',
       },

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

@@ -71,6 +71,25 @@ type InferredResource = {
   resourceVersion: string;
 };
 
+const DOC_TYPE_LABELS: Record<string, string> = {
+  adrs: 'ADR',
+  runbooks: 'Runbook',
+  contracts: 'Contract',
+  troubleshooting: 'Troubleshooting',
+  guides: 'Guide',
+};
+
+/** Human label for a doc type folder, e.g. `guides` → "Guide", `release-notes` → "Release Notes". */
+export const getResourceDocTypeLabel = (type: string): string => {
+  if (DOC_TYPE_LABELS[type]) return DOC_TYPE_LABELS[type];
+  const normalized = type
+    .split(/[-_\s]+/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ');
+  return normalized || 'Doc';
+};
+
 let memoryCache: ResourceDocEntry[] | null = null;
 let memoryCategoryCache: ResourceDocCategoryEntry[] | null = null;
 let memoryResourceLookupCache: Record<ResourceCollection, ResourceLookup> | null = null;

package/eventcatalog/src/enterprise/fields/pages/fields.astro

@@ -1,4 +1,6 @@
 ---
+// Visualiser styles ship in the page head so ClientRouter navigations keep them (see NodeGraph.astro).
+import '@eventcatalog/visualiser/styles-core.css';
 import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
 import FieldsExplorer from '@components/FieldsExplorer/FieldsExplorer';
 import { isEventCatalogScaleEnabled } from '@utils/feature';

package/eventcatalog/src/enterprise/tools/catalog-tools.ts

@@ -310,7 +310,7 @@ export async function getSchemaForResource(params: { resourceId: string; resourc
     const schemaEntries = await getCollection('schemas');
     const schemas = schemaEntries.filter(
       (schema) =>
-        schema.data.message.collection === params.resourceCollection &&
+        schema.data.message.collectionName === params.resourceCollection &&
         schema.data.message.id === params.resourceId &&
         schema.data.message.version === params.resourceVersion
     );

package/eventcatalog/src/pages/architecture/[type]/[id]/[version]/index.astro

@@ -24,7 +24,7 @@ const specifications = type === 'services' ? getSpecificationsForService(props)
 <VerticalSideBarLayout title={pageTitle}>
   <main class="flex docs-layout min-h-full bg-[rgb(var(--ec-page-bg))]">
     <div class="flex docs-layout w-full">
-      <div class="w-full lg:mr-2 pr-24 py-8 bg-[rgb(var(--ec-page-bg))]">
+      <div class="w-full min-w-0 lg:mr-2 pr-24 py-8 bg-[rgb(var(--ec-page-bg))]">
         {type === 'domains' && <DomainGrid domain={domain} client:load />}
         {type === 'systems' && <SystemGrid system={props} client:load />}
         {

package/eventcatalog/src/pages/docs/[type]/[id]/[version]/[docType]/[docId]/[docVersion]/index.astro

@@ -8,7 +8,8 @@ import CopyAsMarkdown from '@components/CopyAsMarkdown';
 import Badge from '@components/Badge.astro';
 import { buildUrl } from '@utils/url-builder';
 import { AlignLeftIcon, HistoryIcon } from 'lucide-react';
-import { isEventCatalogChatEnabled, isResourceDocsEnabled } from '@utils/feature';
+import { isEventCatalogChatEnabled, isMarkdownDownloadEnabled, isResourceDocsEnabled } from '@utils/feature';
+import { getResourceDocTypeLabel } from '@utils/collections/resource-docs';
 import { getIcon } from '@utils/badges';
 import { collectionToResourceMap } from '@utils/collections/util';
 
@@ -51,28 +52,28 @@ const pagefindAttributes =
 <VerticalSideBarLayout title={pageTitle} description={props.data.summary}>
   <main class="flex docs-layout min-h-full bg-[rgb(var(--ec-page-bg))]" {...pagefindAttributes}>
     <div class="flex docs-layout w-full">
-      <div class="w-full lg:mr-2 pr-24 py-8 bg-[rgb(var(--ec-page-bg))]">
-        <div class="border-b border-[rgb(var(--ec-page-border))] md:pb-2">
-          <div>
-            <div class="flex items-center">
-              <div class="flex items-center gap-2">
-                <h2 id="doc-page-header" class="text-2xl md:text-4xl font-bold text-[rgb(var(--ec-page-text))]">{title}</h2>
-              </div>
-            </div>
+      <div class="w-full min-w-0 lg:mr-2 pr-24 py-8 bg-[rgb(var(--ec-page-bg))]">
+        {/* Header mirrors the latest-doc page ([docId]/index.astro) and the resource page. */}
+        <div class="border-b border-[rgb(var(--ec-page-border))] md:pb-3 pt-4">
+          <div class="flex flex-col gap-4">
+            <span class="text-xs md:text-sm font-semibold text-[rgb(var(--ec-accent))] capitalize">
+              {getResourceDocTypeLabel(props.data.type)}
+            </span>
+            <h2 id="doc-page-header" class="text-2xl md:text-4xl font-bold text-[rgb(var(--ec-page-text))]">{title}</h2>
           </div>
           {
             props.data.summary && (
-              <p class="text-base pt-2 text-[rgb(var(--ec-page-text-muted))] font-light">{props.data.summary}</p>
+              <p class="text-base pt-4 text-[rgb(var(--ec-page-text-muted))] font-light">{props.data.summary}</p>
             )
           }
           {
             badges.length > 0 && (
-              <div class="flex flex-wrap gap-1.5 py-3">
+              <div class="flex flex-wrap gap-1.5 pt-4">
                 {badges.map((badge: any) => <Badge badge={badge} />)}
               </div>
             )
           }
-          <div class="pt-4">
+          <div class="pt-5">
             <CopyAsMarkdown
               client:only="react"
               variant="toolbar"
@@ -80,9 +81,9 @@ const pagefindAttributes =
               chatQuery={chatQuery}
               chatEnabled={chatEnabled}
               editUrl=""
-              markdownDownloadEnabled={true}
+              markdownDownloadEnabled={isMarkdownDownloadEnabled()}
               rssFeedEnabled={false}
-              preferChatAsDefault={false}
+              preferChatAsDefault={chatEnabled}
             />
           </div>
         </div>
@@ -100,7 +101,7 @@ const pagefindAttributes =
             )
           }
         </div>
-        <div class="prose py-4 max-w-none">
+        <div class="prose prose-md pt-8 pb-4 w-full text-[15px]">
           <Content components={components(props)} />
         </div>
       </div>

package/eventcatalog/src/pages/docs/[type]/[id]/[version]/[docType]/[docId]/index.astro

@@ -8,9 +8,10 @@ import CopyAsMarkdown from '@components/CopyAsMarkdown';
 import Badge from '@components/Badge.astro';
 import { buildUrl } from '@utils/url-builder';
 import { AlignLeftIcon, HistoryIcon } from 'lucide-react';
-import { isEventCatalogChatEnabled, isResourceDocsEnabled } from '@utils/feature';
+import { isEventCatalogChatEnabled, isMarkdownDownloadEnabled, isResourceDocsEnabled } from '@utils/feature';
 import { getIcon } from '@utils/badges';
 import { collectionToResourceMap } from '@utils/collections/util';
+import { getResourceDocTypeLabel } from '@utils/collections/resource-docs';
 
 import { Page } from './_index.data';
 
@@ -36,6 +37,7 @@ const docsBasePath = `/docs/${props.data.resourceCollection}/${props.data.resour
 const singularResourceName =
   collectionToResourceMap[props.data.resourceCollection as keyof typeof collectionToResourceMap] ??
   props.data.resourceCollection.slice(0, props.data.resourceCollection.length - 1);
+const typeLabel = getResourceDocTypeLabel(props.data.type);
 const chatEnabled = isEventCatalogChatEnabled();
 const chatQuery = `Tell me about the ${props.data.type} doc "${title}" for ${props.data.resourceId} (version ${props.data.version})`;
 
@@ -51,20 +53,22 @@ const pagefindAttributes =
 <VerticalSideBarLayout title={pageTitle} description={props.data.summary}>
   <main class="flex docs-layout min-h-full bg-[rgb(var(--ec-page-bg))]" {...pagefindAttributes}>
     <div class="flex docs-layout w-full">
-      <div class="w-full lg:mr-2 pr-24 py-8 bg-[rgb(var(--ec-page-bg))]">
-        <div class="border-b border-[rgb(var(--ec-page-border))] md:pb-2">
+      <div class="w-full min-w-0 lg:mr-2 pr-24 py-8 bg-[rgb(var(--ec-page-bg))]">
+        {/* Header mirrors the resource page (docs/[type]/[id]/[version]/index.astro) so docs feel like part of the resource. */}
+        <div class="border-b border-[rgb(var(--ec-page-border))] md:pb-3 pt-4">
           <div class="flex flex-col gap-4">
-            <div class="flex items-center gap-4">
-              <h2 id="doc-page-header" class="text-2xl md:text-4xl font-bold text-[rgb(var(--ec-page-text))]">{title}</h2>
-            </div>
-            {props.data.summary && <p class="text-base text-[rgb(var(--ec-page-text-muted))] font-light">{props.data.summary}</p>}
-            {
-              badges.length > 0 && (
-                <div class="flex flex-wrap gap-1.5 py-1">
-                  {badges.map((badge: any) => <Badge badge={badge} />)}
-                </div>
-              )
-            }
+            <span class="text-xs md:text-sm font-semibold text-[rgb(var(--ec-accent))] capitalize">{typeLabel}</span>
+            <h2 id="doc-page-header" class="text-2xl md:text-4xl font-bold text-[rgb(var(--ec-page-text))]">{title}</h2>
+          </div>
+          {props.data.summary && <p class="text-base pt-4 text-[rgb(var(--ec-page-text-muted))] font-light">{props.data.summary}</p>}
+          {
+            badges.length > 0 && (
+              <div class="flex flex-wrap gap-1.5 pt-4">
+                {badges.map((badge: any) => <Badge badge={badge} />)}
+              </div>
+            )
+          }
+          <div class="pt-5">
             <CopyAsMarkdown
               client:only="react"
               variant="toolbar"
@@ -72,9 +76,9 @@ const pagefindAttributes =
               chatQuery={chatQuery}
               chatEnabled={chatEnabled}
               editUrl=""
-              markdownDownloadEnabled={true}
+              markdownDownloadEnabled={isMarkdownDownloadEnabled()}
               rssFeedEnabled={false}
-              preferChatAsDefault={false}
+              preferChatAsDefault={chatEnabled}
             />
           </div>
         </div>
@@ -92,7 +96,7 @@ const pagefindAttributes =
             )
           }
         </div>
-        <div class="prose py-4 max-w-none">
+        <div class="prose prose-md pt-8 pb-4 w-full text-[15px]">
           <Content components={components(props)} />
         </div>
       </div>

package/eventcatalog/src/pages/docs/[type]/[id]/[version]/graphql/[filename].astro

@@ -66,7 +66,7 @@ const pagefindAttributes =
 <VerticalSideBarLayout title={pageTitle} description={`GraphQL schema for ${data.name}`}>
   <main class="flex docs-layout min-h-full bg-[rgb(var(--ec-page-bg))]" {...pagefindAttributes}>
     <div class="flex docs-layout w-full">
-      <div class="w-full lg:mr-2 pr-24 py-8 bg-[rgb(var(--ec-page-bg))]">
+      <div class="w-full min-w-0 lg:mr-2 pr-24 py-8 bg-[rgb(var(--ec-page-bg))]">
         <div class="border-b border-[rgb(var(--ec-page-border))] md:pb-2">
           <div>
             <div class="flex justify-between items-start">

package/eventcatalog/src/pages/docs/[type]/[id]/[version]/index.astro

@@ -408,8 +408,8 @@ if (!isAdrPage && !hasCurrentFlowEmbed && !hasCurrentPageNodeGraph) {
 <VerticalSideBarLayout title={pageTitle} description={props.data.summary}>
   <main class="flex docs-layout min-h-full bg-[rgb(var(--ec-page-bg))]" {...pagefindAttributes}>
     <div class="flex docs-layout w-full">
-      <div class="w-full lg:mr-2 pr-24 py-8 bg-[rgb(var(--ec-page-bg))]">
-        <div class="border-b border-[rgb(var(--ec-page-border))] md:pb-6 pt-4">
+      <div class="w-full min-w-0 lg:mr-2 pr-24 py-8 bg-[rgb(var(--ec-page-bg))]">
+        <div class="border-b border-[rgb(var(--ec-page-border))] md:pb-3 pt-4">
           <div>
             <div>
               <div class="flex flex-col gap-4">
@@ -447,7 +447,7 @@ if (!isAdrPage && !hasCurrentFlowEmbed && !hasCurrentPageNodeGraph) {
               </div>
             </div>
 
-            <h2 class="text-base pt-4 text-[rgb(var(--ec-page-text-muted))] font-light">{props.data.summary}</h2>
+            <p class="text-base pt-4 text-[rgb(var(--ec-page-text-muted))] font-light">{props.data.summary}</p>
             {
               badges && (
                 <div class="flex flex-wrap gap-1.5 pt-4">
@@ -596,7 +596,7 @@ if (!isAdrPage && !hasCurrentFlowEmbed && !hasCurrentPageNodeGraph) {
           }
         </div>
 
-        <div class="prose prose-md py-4 w-full text-[15px]">
+        <div class="prose prose-md pt-8 pb-4 w-full text-[15px]">
           <Content components={components(props)} />
         </div>
         <div data-pagefind-ignore>

package/eventcatalog/src/pages/docs/[type]/[id]/[version]/resources/index.astro

@@ -29,6 +29,8 @@ const hrefForResource = (collection: SystemResourceCollection, id: string, versi
   return buildUrl(`/docs/${collection}/${id}/${version}`);
 };
 
+const ownerTypeLabel = ownerCollection === 'domains' ? 'Domain' : 'System';
+
 const resources: SystemResourceItem[] = resourceGroups.flatMap(({ collection, items }) =>
   items.map((item: any) => ({
     collection,
@@ -45,16 +47,22 @@ const resources: SystemResourceItem[] = resourceGroups.flatMap(({ collection, it
 <VerticalSideBarLayout title={`${data.name} | Resources`}>
   <main class="flex docs-layout min-h-full bg-[rgb(var(--ec-page-bg))]">
     <div class="flex docs-layout w-full">
-      <div class="w-full lg:mr-2 pr-24 py-8 bg-[rgb(var(--ec-page-bg))]">
-        <div class="border-b border-[rgb(var(--ec-page-border))] pb-4">
-          <h2 class="text-2xl md:text-4xl font-bold text-[rgb(var(--ec-page-text))]">{data.name} Resources</h2>
-          <h2 class="text-lg pt-2 text-[rgb(var(--ec-page-text-muted))] font-light">
-            A group of resources that are mapped to the {data.name}{' '}
-            {ownerCollection === 'domains' ? 'domain' : 'system'}.
-          </h2>
+      <div class="w-full min-w-0 lg:mr-2 pr-24 py-8 bg-[rgb(var(--ec-page-bg))]">
+        {/* Header mirrors the resource page (docs/[type]/[id]/[version]/index.astro). */}
+        <div class="border-b border-[rgb(var(--ec-page-border))] md:pb-3 pt-4">
+          <div class="flex flex-col gap-4">
+            <span class="text-xs md:text-sm font-semibold text-[rgb(var(--ec-accent))] capitalize">{ownerTypeLabel}</span>
+            <h2 id="doc-page-header" class="text-2xl md:text-4xl font-bold text-[rgb(var(--ec-page-text))]">
+              {data.name} Resources
+            </h2>
+          </div>
+          <p class="text-base pt-4 pb-1 text-[rgb(var(--ec-page-text-muted))] font-light">
+            {resources.length} {resources.length === 1 ? 'resource' : 'resources'} mapped to the {data.name}{' '}
+            {ownerTypeLabel.toLowerCase()}.
+          </p>
         </div>
 
-        <div class="py-8 w-full">
+        <div class="pt-8 pb-4 w-full">
           <SystemResourcesTable resources={resources} client:only="react" />
         </div>
       </div>

package/eventcatalog/src/pages/docs/[type]/[id]/language/[dictionaryId]/index.astro

@@ -25,90 +25,73 @@ const editUrl = resolveUbiquitousLanguageTermEditUrl({
   configEditUrl: config.editUrl,
 });
 
-marked.setOptions({
-  breaks: true,
-  gfm: true,
-});
+// Pass options per call rather than via `marked.setOptions`, which mutates module-global
+// state and leaks between pages (and between HMR reloads) in the same process.
+const renderMarkdown = (markdown: string) => marked.parse(markdown, { gfm: true, breaks: false }) as string;
+
+const TermIcon = ubiquitousLanguage.icon
+  ? ((LucideIcons as unknown as Record<string, LucideIcons.LucideIcon>)[ubiquitousLanguage.icon] ?? null)
+  : null;
 
+// Badges double as navigation back up the hierarchy: the owning domain and its glossary.
 const badges = [
   {
     content: props.domain.name,
     icon: RectangleGroupIcon,
+    url: buildUrl(`/docs/${props.type}/${props.domainId}/${props.domain.latestVersion}`),
+  },
+  {
+    content: 'Ubiquitous Language',
+    icon: LucideIcons.BookOpen,
+    url: buildUrl(`/docs/${props.type}/${props.domainId}/language`),
   },
 ];
 ---
 
 <VerticalSideBarLayout title={pageTitle} description={ubiquitousLanguage.summary}>
   <main
-    class="flex sm:px-8 docs-layout min-h-full max-w-7xl bg-[rgb(var(--ec-page-bg))]"
+    class="flex docs-layout min-h-full bg-[rgb(var(--ec-page-bg))]"
     data-pagefind-body
     data-pagefind-meta={`title:${pageTitle}`}
   >
     <div class="flex docs-layout w-full">
-      <div class="w-full lg:mr-2 pr-8 py-8 min-h-[50em]">
-        {/* Breadcrumb */}
-        <nav class="mb-4 flex items-center space-x-2 text-sm text-[rgb(var(--ec-page-text-muted))]" aria-label="Breadcrumb">
-          <a
-            href={buildUrl(`/docs/${props.type}/${props.domainId}/${props.domain.latestVersion}`)}
-            class="hover:text-[rgb(var(--ec-page-text))] hover:underline flex items-center gap-2"
-          >
-            <RectangleGroupIcon className="h-4 w-4" />
-            {props.domain.name}
-          </a>
-          <svg class="h-4 w-4" fill="none" stroke="currentColor" viewBox="0 0 24 24" stroke-width="2">
-            <path stroke-linecap="round" stroke-linejoin="round" d="M9 5l7 7-7 7"></path>
-          </svg>
-          <a
-            href={buildUrl(`/docs/${props.type}/${props.domainId}/language`)}
-            class="hover:text-[rgb(var(--ec-page-text))] hover:underline flex items-center gap-2"
-          >
-            {
-              (() => {
-                const BookOpen = LucideIcons.BookOpen;
-                //@ts-ignore
-                return <BookOpen className="h-4 w-4" />;
-              })()
-            }
-            Ubiquitous Language Explorer
-          </a>
-          <svg class="h-4 w-4" fill="none" stroke="currentColor" viewBox="0 0 24 24" stroke-width="2">
-            <path stroke-linecap="round" stroke-linejoin="round" d="M9 5l7 7-7 7"></path>
-          </svg>
-          <span class="text-[rgb(var(--ec-page-text))]">{ubiquitousLanguage.name}</span>
-        </nav>
-
-        <div class="border-b border-[rgb(var(--ec-page-border))] flex justify-between items-start md:pb-2">
-          <div>
-            <h2 id="doc-page-header" class="text-2xl md:text-4xl font-bold text-[rgb(var(--ec-page-text))]">
-              {ubiquitousLanguage.name}
-            </h2>
-            <p class="text-lg pt-2 text-[rgb(var(--ec-page-text-muted))] font-light">{ubiquitousLanguage.summary}</p>
-            <!-- Add badge -->
-            {
-              badges && badges.length > 0 && (
-                <div class="flex flex-wrap gap-3 py-4">
-                  {badges.map((badge: any) => {
-                    return <Badge badge={badge} />;
-                  })}
-                </div>
-              )
-            }
+      <div class="w-full min-w-0 lg:mr-2 pr-24 py-8 min-h-[50em]">
+        {/* Header mirrors the resource page (docs/[type]/[id]/[version]/index.astro). */}
+        <div class="border-b border-[rgb(var(--ec-page-border))] md:pb-3 pt-4">
+          <div class="flex flex-col gap-4">
+            <span class="text-xs md:text-sm font-semibold text-[rgb(var(--ec-accent))] capitalize">Term</span>
+            <div class="flex items-center gap-3">
+              {
+                TermIcon && (
+                  <div class="flex items-center justify-center w-8 h-8 md:w-10 md:h-10 rounded-md bg-[rgb(var(--ec-accent-subtle))] shrink-0">
+                    <TermIcon className="w-5 h-5 md:w-6 md:h-6 text-[rgb(var(--ec-accent))]" />
+                  </div>
+                )
+              }
+              <h2 id="doc-page-header" class="text-2xl md:text-4xl font-bold text-[rgb(var(--ec-page-text))]">
+                {ubiquitousLanguage.name}
+              </h2>
+            </div>
+          </div>
+          {
+            ubiquitousLanguage.summary && (
+              <p class="text-base pt-4 text-[rgb(var(--ec-page-text-muted))] font-light">{ubiquitousLanguage.summary}</p>
+            )
+          }
+          <div class="flex flex-wrap gap-1.5 pt-4 pb-1">
+            {badges.map((badge: any) => <Badge badge={badge} />)}
           </div>
         </div>
 
-        {
-          ubiquitousLanguage.description && (
-            <div class="prose prose-md py-4 max-w-none" set:html={marked.parse(ubiquitousLanguage.description)} />
-          )
-        }
-
-        {
-          !ubiquitousLanguage.description && (
-            <div class="prose prose-md py-4 max-w-none">
+        <div class="prose prose-md pt-8 pb-4 w-full text-[15px]">
+          {
+            ubiquitousLanguage.description ? (
+              <Fragment set:html={renderMarkdown(ubiquitousLanguage.description)} />
+            ) : (
               <p>No description for {ubiquitousLanguage.name} available.</p>
-            </div>
-          )
-        }
+            )
+          }
+        </div>
 
         <Footer />
         <div class="flex justify-end">