@eventcatalog/core 4.10.14 → 4.11.0

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

@@ -1,6 +1,8 @@
 ---
 import type { PageTypes } from '@types';
-import { getCollection } from 'astro:content';
+import { getCollection, render } from 'astro:content';
+import components from '@components/MDX/components';
+import { getExampleEntriesForMessage, getExampleEntryDetails } from '@utils/collections/examples';
 import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
 import { Page } from './_index.data';
 import SchemaPageViewer from '@components/SchemaExplorer/SchemaPageViewer';
@@ -9,8 +11,24 @@ import { sortVersioned } from '@utils/collections/util';
 import { isEventCatalogScaleEnabled } from '@utils/feature';
 import { resourceFileExists, readResourceFile } from '@utils/resource-files';
 import path from 'node:path';
-import type { SchemaItem } from '@components/SchemaExplorer/types';
+import type { FlowUsage, SchemaItem } from '@components/SchemaExplorer/types';
 import { getExamplesForResource } from '@utils/collections/examples';
+import { getSchemaRelationshipReference } from '@components/SchemaExplorer/utils';
+import { getSchemaExtensionForFormat } from '@utils/collections/schemas';
+import { getFlowsForMessages } from '@utils/collections/flows';
+import { attachFlowGraphs, getMessageUsageGraph } from '@utils/schema-usage-graph';
+// Ships the visualiser CSS in the page head so it survives ClientRouter navigations (see NodeGraph.astro).
+import '@eventcatalog/visualiser/styles-core.css';
+
+/** Reduce hydrated resource entries to the details the schema page renders. */
+const toSchemaRelationships = (references: any[] | undefined) =>
+  (references ?? []).map((reference) => getSchemaRelationshipReference(reference));
+const toMessageChannels = (channels: any[] | undefined) =>
+  (channels ?? []).map((channel) => ({
+    id: channel.data.id,
+    version: channel.data.version,
+    ...(channel.data.name ? { name: channel.data.name } : {}),
+  }));
 
 export const prerender = Page.prerender;
 export const getStaticPaths = Page.getStaticPaths;
@@ -26,6 +44,14 @@ const contractPath = Astro.url.searchParams.get('contract') || (props as any).co
 
 let currentMessage: SchemaItem | null = null;
 let sortedVersions: SchemaItem[] = [];
+// Examples rendered through the MDX pipeline so they can use EventCatalog's components.
+let renderedExamples: {
+  fileName: string;
+  title: string;
+  summary?: string;
+  Content: Awaited<ReturnType<typeof render>>['Content'];
+}[] = [];
+let exampleComponents: ReturnType<typeof components> | undefined;
 let pageTitle = `${type} | ${data.name}`.replace(/^\w/, (c) => c.toUpperCase());
 
 if (isDataProduct && contractPath) {
@@ -79,6 +105,7 @@ if (isDataProduct && contractPath) {
   // Handle regular messages (events, commands, queries)
   const [allItems, schemaEntries] = await Promise.all([pageDataLoader[type](), getCollection('schemas')]);
   const versions = allItems.filter((item) => item.data.id === data.id);
+  const flowsByMessage = await getFlowsForMessages(versions);
   const schemasForMessage = schemaEntries.filter(
     (schema) => schema.data.message.collectionName === type && schema.data.message.id === data.id
   );
@@ -89,44 +116,81 @@ if (isDataProduct && contractPath) {
   };
 
   // Transform to SchemaItems
-  const availableVersions = versions
-    .map((message) => {
-      try {
-        const schema = getSchemaForVersion(message.data.version);
-        if (!schema) return null;
+  const availableVersions = (
+    await Promise.all(
+      versions.map(async (message) => {
+        try {
+          const schema = getSchemaForVersion(message.data.version);
+          const messageFlows: FlowUsage[] =
+            flowsByMessage.get(`${message.collection}:${message.data.id}:${message.data.version}`) ?? [];
+          if (!schema) return null;
 
-        const schemaPath = schema.data.file || schema.data.source.path || '';
-        const schemaExtension = path.extname(schemaPath).slice(1);
+          const schemaPath = schema.data.file || schema.data.source.path || '';
+          const schemaExtension = path.extname(schemaPath).slice(1) || getSchemaExtensionForFormat(schema.data.format);
 
-        return {
-          collection: message.collection,
-          data: {
-            id: message.data.id,
-            name: schema.data.message.name || message.data.name,
-            version: message.data.version,
-            summary: schema.data.message.summary || message.data.summary,
-            schemaPath,
-            // @ts-ignore
-            producers: message.data.producers || [],
-            // @ts-ignore
-            consumers: message.data.consumers || [],
-          },
-          schemaContent: schema.data.content || '',
-          schemaExtension,
-          examples: getExamplesForResource(message),
-        } as SchemaItem;
-      } catch (error) {
-        console.error(`Error reading schema for ${message.data.id}:`, error);
-        return null;
-      }
-    })
-    .filter((v): v is SchemaItem => v !== null);
+          return {
+            collection: message.collection,
+            data: {
+              id: message.data.id,
+              name: schema.data.message.name || message.data.name,
+              version: message.data.version,
+              summary: schema.data.message.summary || message.data.summary,
+              schemaPath,
+              // @ts-ignore
+              producers: toSchemaRelationships(message.data.producers),
+              // @ts-ignore
+              consumers: toSchemaRelationships(message.data.consumers),
+              flows: await (message.data.version === data.version
+                ? attachFlowGraphs(messageFlows, { id: message.data.id, version: message.data.version })
+                : messageFlows),
+              // @ts-ignore
+              channels: toMessageChannels(message.data.messageChannels),
+            },
+            schemaContent: schema.data.content || '',
+            schemaExtension,
+            ...(schema.data.name ? { schemaName: schema.data.name } : {}),
+            ...(schema.data.ref ? { schemaRef: schema.data.ref, source: schema.data.source } : {}),
+            examples: getExamplesForResource(message),
+            // Only the version being viewed needs the usage graph; other versions load their own page.
+            ...(message.data.version === data.version
+              ? {
+                  graph: await getMessageUsageGraph({
+                    collection: message.collection,
+                    id: message.data.id,
+                    version: message.data.version,
+                  }),
+                }
+              : {}),
+          } as SchemaItem;
+        } catch (error) {
+          console.error(`Error reading schema for ${message.data.id}:`, error);
+          return null;
+        }
+      })
+    )
+  ).filter((v): v is SchemaItem => v !== null);
 
   sortedVersions = sortVersioned(availableVersions, (item) => item.data.version);
   currentMessage = sortedVersions.find((v) => v.data.version === data.version) ?? null;
+
+  const messageEntry = versions.find((item) => item.data.version === data.version);
+  if (messageEntry?.filePath) {
+    const exampleEntries = getExampleEntriesForMessage(await getCollection('examples'), messageEntry.filePath);
+    const examplesDir = path.join(path.dirname(messageEntry.filePath), 'examples');
+    renderedExamples = await Promise.all(
+      exampleEntries.map(async (entry) => ({
+        ...getExampleEntryDetails(entry, examplesDir),
+        Content: (await render(entry)).Content,
+      }))
+    );
+    exampleComponents = components(messageEntry);
+  }
 }
 
 const apiAccessEnabled = isEventCatalogScaleEnabled();
+// Render the requested tab on the server so the page does not flash the default tab before hydration.
+// Static builds cannot see the query string, so the panel also restores the tab on the client.
+const initialTab = Astro.url.searchParams.get('tab') ?? undefined;
 ---
 
 <VerticalSideBarLayout title={pageTitle}>
@@ -134,11 +198,16 @@ const apiAccessEnabled = isEventCatalogScaleEnabled();
     :root[data-embedded='true'] #schema-detail-page {
       height: 100dvh !important;
     }
+    .react-flow__attribution {
+      display: none;
+    }
   </style>
-  {/* The schema viewer is an app-style surface: pull it out of the content gutter so it sits flush against the sidebar. */}
+  {
+    /* The schema viewer is an app-style surface: pull it out of the content gutter so it sits flush against the sidebar. The page scrolls normally; the embedded layout below pins it to the viewport instead. */
+  }
   <div
     id="schema-detail-page"
-    class="h-[calc(100vh-4rem)] overflow-hidden flex flex-col"
+    class="min-h-[calc(100vh-4rem)] flex flex-col"
     style="margin-left: calc(var(--ec-app-content-padding-left, 5rem) * -1); margin-right: calc(var(--ec-app-content-padding-right, 5rem) * -1);"
   >
     {
@@ -148,9 +217,47 @@ const apiAccessEnabled = isEventCatalogScaleEnabled();
           message={currentMessage}
           availableVersions={sortedVersions}
           apiAccessEnabled={apiAccessEnabled}
-          showOwners={false}
-          showProducersConsumers={false}
-        />
+          showOwners={true}
+          showProducersConsumers={true}
+          initialTab={initialTab}
+          hasRenderedExamples={(currentMessage.examples?.length ?? 0) > 0}
+        >
+          {(currentMessage.examples?.length ?? 0) > 0 && (
+            <div slot="examples" class="divide-y divide-[rgb(var(--ec-page-border))]">
+              {currentMessage.examples?.map((example) => {
+                const rendered = renderedExamples.find((candidate) => candidate.fileName === example.fileName);
+                const Content = rendered?.Content;
+                return (
+                  <section
+                    id={`example-${example.fileName.replace(/[^a-zA-Z0-9]+/g, '-')}`}
+                    class="w-full pr-12 py-8 first:pt-0 last:pb-0"
+                  >
+                    {example.summary && <p class="mb-4 text-sm text-[rgb(var(--ec-page-text-muted))]">{example.summary}</p>}
+                    {Content ? (
+                      <div class="prose prose-sm max-w-none prose-h1:mt-0 prose-h1:text-4xl prose-h1:font-bold prose-h1:tracking-tight prose-headings:text-[rgb(var(--ec-page-text))] prose-p:text-[rgb(var(--ec-page-text-muted))] prose-li:text-[rgb(var(--ec-page-text-muted))] prose-strong:text-[rgb(var(--ec-page-text))] prose-a:text-[rgb(var(--ec-accent))] prose-blockquote:border-[rgb(var(--ec-page-border))] prose-hr:border-[rgb(var(--ec-page-border))]">
+                        <Content components={exampleComponents} />
+                      </div>
+                    ) : (
+                      <pre class="overflow-auto rounded-lg border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-code-bg))] p-5 text-sm">
+                        <code>{example.content}</code>
+                      </pre>
+                    )}
+                    {example.usage && (
+                      <div class="mt-5">
+                        <h3 class="mb-2 text-xs font-semibold uppercase tracking-wider text-[rgb(var(--ec-page-text-muted))]">
+                          Usage
+                        </h3>
+                        <pre class="overflow-auto rounded-lg border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-code-bg))] p-5 text-sm">
+                          <code>{example.usage}</code>
+                        </pre>
+                      </div>
+                    )}
+                  </section>
+                );
+              })}
+            </div>
+          )}
+        </SchemaPageViewer>
       ) : (
         <div class="p-8 flex items-center justify-center h-full text-[rgb(var(--ec-page-text-muted))]">
           Schema not found or could not be loaded.

package/eventcatalog/src/pages/schemas/explorer/index.astro

@@ -3,6 +3,8 @@ import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
 import SchemaExplorer from '@components/SchemaExplorer/SchemaExplorer';
 import { isEventCatalogScaleEnabled } from '@utils/feature';
 import { Page } from './_index.data';
+// Ships the visualiser CSS in the page head for the Usage tab's node graph (see NodeGraph.astro).
+import '@eventcatalog/visualiser/styles-core.css';
 
 export const prerender = Page.prerender;
 export const getStaticPaths = Page.getStaticPaths;
@@ -14,6 +16,9 @@ const apiAccessEnabled = isEventCatalogScaleEnabled();
 
 <VerticalSideBarLayout title="Schema Explorer - EventCatalog" showNestedSideBar={false}>
   <style is:global>
+    .react-flow__attribution {
+      display: none;
+    }
     #eventcatalog-header {
       left: calc(var(--ec-vertical-nav-width, 14rem) + var(--ec-schema-sidebar-width, 360px)) !important;
     }

package/eventcatalog/src/remark-plugins/code-group.ts

@@ -0,0 +1,39 @@
+type Node = {
+  type: string;
+  name?: string;
+  lang?: string;
+  meta?: string | null;
+  children?: Node[];
+  attributes?: { type: string; name: string; value: string }[];
+};
+
+/** Keep fenced code in the normal highlighting pipeline, with a panel per fence. */
+export function remarkCodeGroup() {
+  return (tree: Node) => {
+    const walk = (node: Node) => {
+      if (node.type === 'mdxJsxFlowElement' && node.name === 'CodeGroup') {
+        node.children = node.children?.map((child, index) => {
+          if (child.type !== 'code') return child;
+          const meta = child.meta?.trim() ?? '';
+          const explicit = meta.match(/(?:^|\s)title=(?:"([^"]*)"|'([^']*)')/);
+          const bare = meta.match(/^(?:"([^"]+)"|'([^']+)'|([^\s={}]+))(?=\s|$)/);
+          const label =
+            explicit?.[1] ?? explicit?.[2] ?? bare?.[1] ?? bare?.[2] ?? bare?.[3] ?? child.lang ?? `Code ${index + 1}`;
+          // Bare titles are Mintlify syntax; remove them before Expressive Code reads modifiers.
+          if (!explicit && bare) child.meta = meta.slice(bare[0].length).trim();
+          return {
+            type: 'mdxJsxFlowElement',
+            name: 'div',
+            attributes: [
+              { type: 'mdxJsxAttribute', name: 'data-code-panel', value: label },
+              ...(child.lang ? [{ type: 'mdxJsxAttribute', name: 'data-code-lang', value: child.lang }] : []),
+            ],
+            children: [child],
+          };
+        });
+      }
+      node.children?.forEach(walk);
+    };
+    walk(tree);
+  };
+}

package/eventcatalog/src/remark-plugins/markdown-code-group.ts

@@ -0,0 +1,59 @@
+type Node = {
+  type: string;
+  value?: string;
+  lang?: string;
+  meta?: string | null;
+  children?: Node[];
+  data?: Record<string, unknown>;
+};
+
+/** Recognize only CodeGroup wrappers in plain Markdown; never enable arbitrary HTML or JSX. */
+export function remarkMarkdownCodeGroup() {
+  return (tree: Node) => {
+    const walk = (parent: Node) => {
+      const children = parent.children;
+      if (!children) return;
+      for (let index = 0; index < children.length; index++) {
+        const opening = children[index].type === 'html' && children[index].value?.trim().match(/^<CodeGroup\b([^>]*)>$/);
+        if (!opening) {
+          walk(children[index]);
+          continue;
+        }
+        const end = children.findIndex(
+          (child, i) => i > index && child.type === 'html' && child.value?.trim() === '</CodeGroup>'
+        );
+        if (end === -1) continue;
+        const blocks = children.slice(index + 1, end);
+        if (!blocks.length || blocks.some((child) => child.type !== 'code')) continue;
+        const className = opening[1].match(/\bclassName=(?:"([^"]*)"|'([^']*)')/);
+        const dropdown = /(?:^|\s)dropdown(?:\s|$|=\{true\})/.test(opening[1]);
+        children.splice(index, end - index + 1, {
+          type: 'codeGroup',
+          data: {
+            hName: 'div',
+            hProperties: {
+              'data-code-group': 'true',
+              'data-dropdown': String(dropdown),
+              className: className?.[1] ?? className?.[2],
+            },
+          },
+          children: blocks.map((code, i) => {
+            const meta = code.meta?.trim() ?? '';
+            const title =
+              meta.match(/(?:^|\s)title=(?:"([^"]*)"|'([^']*)')/) ?? meta.match(/^(?:"([^"]+)"|'([^']+)'|([^\s={}]+))/);
+            const label = title?.[1] ?? title?.[2] ?? title?.[3] ?? code.lang ?? `Code ${i + 1}`;
+            return {
+              type: 'codeGroupPanel',
+              data: {
+                hName: 'div',
+                hProperties: { 'data-code-panel': label, ...(code.lang ? { 'data-code-lang': code.lang } : {}) },
+              },
+              children: [code],
+            };
+          }),
+        });
+      }
+    };
+    walk(tree);
+  };
+}

package/eventcatalog/src/remark-plugins/markdown-columns.ts

@@ -0,0 +1,66 @@
+type Node = {
+  type: string;
+  value?: string;
+  children?: Node[];
+  data?: Record<string, unknown>;
+};
+
+const tagPattern = /<\/?(?:Columns|Column)\b[^>]*>/g;
+const attribute = (attrs: string, name: string) =>
+  attrs
+    .match(new RegExp(`\\b${name}=(?:"([^"]*)"|'([^']*)'|\\{([\\d.]+)\\})`))
+    ?.slice(1)
+    .find((value) => value !== undefined);
+
+/** Support the layout tags in Markdown without evaluating JSX or allowing arbitrary HTML. */
+export function remarkMarkdownColumns() {
+  return (tree: Node) => {
+    const walk = (parent: Node) => {
+      if (!parent.children) return;
+      // Markdown may put adjacent opening/closing tags in the same HTML node.
+      const children = parent.children.flatMap((node) => {
+        if (node.type !== 'html' || !node.value || node.value.replace(tagPattern, '').trim()) return [node];
+        return Array.from(node.value.matchAll(tagPattern), ([value]) => ({ type: 'html', value }));
+      });
+      parent.children = children;
+      for (let i = 0; i < children.length; i++) {
+        const opening = children[i].type === 'html' && children[i].value?.trim().match(/^<(Columns|Column)\b([^>]*)>$/);
+        if (!opening) {
+          walk(children[i]);
+          continue;
+        }
+        const name = opening[1];
+        let depth = 1;
+        let end = i + 1;
+        for (; end < children.length; end++) {
+          if (children[end].type !== 'html') continue;
+          const value = children[end].value?.trim();
+          if (value?.match(new RegExp(`^<${name}\\b[^>]*>$`))) depth++;
+          if (value === `</${name}>` && --depth === 0) break;
+        }
+        if (end === children.length) continue;
+        const attrs = opening[2];
+        const wrapper: Node = {
+          type: 'columnLayout',
+          data: {
+            hName: 'div',
+            hProperties: {
+              ...(name === 'Columns'
+                ? {
+                    'data-columns': 'true',
+                    'data-cols': attribute(attrs, 'cols') ?? '2',
+                    'data-ratio': attribute(attrs, 'ratio'),
+                  }
+                : { 'data-column': 'true', 'data-sticky': String(/(?:^|\s)sticky(?:\s|$|=\{true\})/.test(attrs)) }),
+              className: attribute(attrs, 'className'),
+            },
+          },
+          children: children.slice(i + 1, end),
+        };
+        walk(wrapper);
+        children.splice(i, end - i + 1, wrapper);
+      }
+    };
+    walk(tree);
+  };
+}

package/eventcatalog/src/utils/collections/examples.ts

@@ -1,15 +1,27 @@
 import fs from 'fs';
 import path from 'path';
+import matter from 'gray-matter';
 import yaml from 'js-yaml';
 import { getResourceBasePath } from '@utils/resource-files';
 
+/**
+ * A usage example for a message: any text file inside the message's `examples/` folder.
+ */
 export interface MessageExample {
+  /** File path relative to the `examples/` folder, for example `basic-order.json`. */
   fileName: string;
+  /** Display title: frontmatter `title`, else the first level-one heading, else the file name. */
   title: string;
+  /** File extension without the leading dot. */
   extension: string;
-  content: string;
+  /** Markdown is rendered as prose; other formats and unsupported MDX are rendered as source. */
+  renderMode: 'markdown' | 'code';
+  /** Optional short description from frontmatter `summary`. */
   summary?: string;
+  /** Optional usage instructions from the legacy examples config. */
   usage?: string;
+  /** File contents. Markdown frontmatter is removed. */
+  content: string;
 }
 
 interface ExampleConfig {
@@ -18,68 +30,148 @@ interface ExampleConfig {
   usage?: string;
 }
 
-function loadConfig(examplesDir: string): Record<string, ExampleConfig> {
-  const yamlPath = path.join(examplesDir, 'examples.config.yaml');
-  const ymlPath = path.join(examplesDir, 'examples.config.yml');
-  const jsonPath = path.join(examplesDir, 'examples.config.json');
-
-  let configPath: string | null = null;
-  if (fs.existsSync(yamlPath)) configPath = yamlPath;
-  else if (fs.existsSync(ymlPath)) configPath = ymlPath;
-  else if (fs.existsSync(jsonPath)) configPath = jsonPath;
+const CONFIG_FILES = new Set(['examples.config.yaml', 'examples.config.yml', 'examples.config.json']);
+const MARKDOWN_EXTENSIONS = new Set(['.md', '.mdx']);
+const CLIENT_RENDERED_MDX_COMPONENTS = new Set(['Column', 'Columns', 'CodeGroup']);
 
+const loadConfig = (examplesDir: string): Record<string, ExampleConfig> => {
+  const configPath = ['examples.config.yaml', 'examples.config.yml', 'examples.config.json']
+    .map((fileName) => path.join(examplesDir, fileName))
+    .find(fs.existsSync);
   if (!configPath) return {};
 
   const raw = fs.readFileSync(configPath, 'utf-8');
-  if (configPath.endsWith('.json')) {
-    return JSON.parse(raw) || {};
-  }
-  return (yaml.load(raw) as Record<string, ExampleConfig>) || {};
-}
+  return configPath.endsWith('.json') ? JSON.parse(raw) || {} : (yaml.load(raw) as Record<string, ExampleConfig>) || {};
+};
 
-const CONFIG_FILES = ['examples.config.yaml', 'examples.config.yml', 'examples.config.json'];
+const humanizeFileName = (fileName: string) =>
+  path
+    .parse(fileName)
+    .name.replace(/[-_]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/^\w/, (character) => character.toUpperCase());
 
-function collectFiles(dir: string, baseDir: string): Omit<MessageExample, 'summary' | 'usage'>[] {
-  const results: Omit<MessageExample, 'summary' | 'usage'>[] = [];
+const collectExampleFiles = (dir: string, baseDir: string): string[] => {
+  const results: string[] = [];
   const entries = fs.readdirSync(dir, { withFileTypes: true });
 
   for (const entry of entries) {
     const fullPath = path.join(dir, entry.name);
     if (entry.isDirectory()) {
-      results.push(...collectFiles(fullPath, baseDir));
-    } else if (entry.isFile() && !CONFIG_FILES.includes(entry.name)) {
-      results.push({
-        fileName: path.relative(baseDir, fullPath),
-        title: path.parse(entry.name).name,
-        extension: path.parse(entry.name).ext.slice(1),
-        content: fs.readFileSync(fullPath, 'utf-8'),
-      });
+      results.push(...collectExampleFiles(fullPath, baseDir));
+    } else if (entry.isFile() && !CONFIG_FILES.has(entry.name)) {
+      results.push(path.relative(baseDir, fullPath));
     }
   }
 
   return results;
+};
+
+const hasUnsupportedMdxComponent = (content: string) =>
+  [...content.matchAll(/<([A-Z][A-Za-z0-9.]*)\b/g)].some((match) => !CLIENT_RENDERED_MDX_COMPONENTS.has(match[1]));
+
+/**
+ * Splits an example file into its title and Markdown body. The title comes from frontmatter,
+ * else the leading level-one heading, else the file name. The body is left as written.
+ */
+export const parseExampleFile = (fileName: string, raw: string): MessageExample => {
+  const { data, content } = matter(raw);
+  const body = content.replace(/^\s*\n/, '');
+  let title = typeof data.title === 'string' && data.title.trim() ? data.title.trim() : undefined;
+  const extension = path.extname(fileName).slice(1).toLowerCase();
+
+  const headingMatch = body.match(/^#[ \t]+(.+)(?:\r?\n|$)/);
+  if (headingMatch) title = title ?? headingMatch[1].trim();
+
+  return {
+    fileName: fileName.replace(/\\/g, '/'),
+    title: title ?? humanizeFileName(fileName),
+    extension,
+    renderMode: extension === 'mdx' && hasUnsupportedMdxComponent(body) ? 'code' : 'markdown',
+    ...(typeof data.summary === 'string' && data.summary.trim() ? { summary: data.summary.trim() } : {}),
+    content: body.trim(),
+  };
+};
+
+const parseRawExampleFile = (fileName: string, raw: string, config: ExampleConfig = {}): MessageExample => ({
+  fileName: fileName.replace(/\\/g, '/'),
+  title: config.name?.trim() || humanizeFileName(fileName),
+  extension: path.extname(fileName).slice(1).toLowerCase(),
+  renderMode: 'code',
+  ...(config.summary?.trim() ? { summary: config.summary.trim() } : {}),
+  ...(config.usage?.trim() ? { usage: config.usage.trim() } : {}),
+  content: raw,
+});
+
+/** The parts of an `examples` collection entry the schema pages need. */
+export interface ExampleEntryLike {
+  id: string;
+  filePath?: string;
+  body?: string;
+  data: { title?: string; summary?: string };
+}
+
+const normalize = (value: string) => path.resolve(value).replace(/\\/g, '/');
+
+/**
+ * Selects the example entries that belong to a message: the files under the `examples/`
+ * folder beside the message file, sorted by path.
+ */
+export function getExampleEntriesForMessage<T extends ExampleEntryLike>(entries: T[], messageFilePath?: string): T[] {
+  if (!messageFilePath) return [];
+  const examplesDir = `${normalize(path.dirname(messageFilePath))}/examples/`;
+
+  return entries
+    .filter((entry) => entry.filePath && normalize(entry.filePath).startsWith(examplesDir))
+    .sort((a, b) => (a.filePath as string).localeCompare(b.filePath as string));
 }
 
+/**
+ * Display details for a collection entry, mirroring `parseExampleFile`: frontmatter title,
+ * else the first level-one heading, else the file name.
+ */
+export function getExampleEntryDetails(entry: ExampleEntryLike, examplesDir?: string) {
+  const fileName =
+    entry.filePath && examplesDir
+      ? path.relative(examplesDir, entry.filePath).replace(/\\/g, '/')
+      : path.basename(entry.filePath ?? entry.id);
+  const parsed = parseExampleFile(fileName, entry.body ?? '');
+
+  return {
+    fileName,
+    title: entry.data.title?.trim() || parsed.title,
+    summary: entry.data.summary?.trim() || parsed.summary,
+  };
+}
+
+/**
+ * Reads usage examples stored in the `examples/` folder next to a message.
+ */
 export function getExamplesForResource(resource: { filePath?: string }): MessageExample[] {
   const basePath = getResourceBasePath(resource);
   if (!basePath) return [];
 
   const examplesDir = path.join(basePath, 'examples');
   if (!fs.existsSync(examplesDir)) return [];
-
   const config = loadConfig(examplesDir);
-  const files = collectFiles(examplesDir, examplesDir);
-
-  return files
-    .map((file) => {
-      const key = file.fileName.replace(/\\/g, '/');
-      const meta = config[key] || {};
-      return {
-        ...file,
-        title: meta.name || file.title,
-        summary: meta.summary,
-        usage: meta.usage,
-      };
-    })
-    .sort((a, b) => a.fileName.localeCompare(b.fileName));
+
+  return collectExampleFiles(examplesDir, examplesDir)
+    .sort((a, b) => a.localeCompare(b))
+    .map((fileName) => {
+      const raw = fs.readFileSync(path.join(examplesDir, fileName), 'utf-8');
+      const normalizedFileName = fileName.replace(/\\/g, '/');
+      const extension = path.extname(fileName).toLowerCase();
+      if (MARKDOWN_EXTENSIONS.has(extension)) {
+        const example = parseExampleFile(fileName, raw);
+        const metadata = config[normalizedFileName];
+        return {
+          ...example,
+          ...(metadata?.name?.trim() ? { title: metadata.name.trim() } : {}),
+          ...(metadata?.summary?.trim() ? { summary: metadata.summary.trim() } : {}),
+          ...(metadata?.usage?.trim() ? { usage: metadata.usage.trim() } : {}),
+        };
+      }
+      return parseRawExampleFile(fileName, raw, config[normalizedFileName]);
+    });
 }