@eventcatalog/core 2.30.8 → 2.31.1

package/eventcatalog/src/enterprise/custom-documentation/pages/index.astro

@@ -0,0 +1,389 @@
+---
+import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
+import { render } from 'astro:content';
+import { buildUrl } from '@utils/url-builder';
+import config from '@config';
+import { AlignLeftIcon } from 'lucide-react';
+import mdxComponents from '@components/MDX/components';
+import OwnersList from '@components/Lists/OwnersList';
+import { getOwner } from '@utils/collections/owners';
+import CustomDocsNav from '@components/SideNav/CustomDocsNav.astro';
+
+const props = Astro.props;
+const doc = props.data;
+const { Content, headings } = await render(props as any);
+const currentSlug = props.id;
+
+// Get sidebar data
+const sidebar = config?.customDocs?.sidebar || [];
+
+// Flatten the sidebar to find previous and next pages
+type FlatItem = {
+  label: string;
+  slug: string;
+};
+
+// Define sidebar section type
+type SidebarSection = {
+  label: string;
+  slug?: string;
+  items?: Array<{
+    label: string;
+    slug: string;
+  }>;
+};
+
+const flattenedItems: FlatItem[] = [];
+
+// Process all sidebar sections to create a flattened array
+sidebar.forEach((section: SidebarSection) => {
+  if (section.slug && !section.items) {
+    flattenedItems.push({
+      label: section.label,
+      slug: section.slug,
+    });
+  }
+  if (section.items) {
+    section.items.forEach((item: { label: string; slug: string }) => {
+      flattenedItems.push({
+        label: item.label,
+        slug: item.slug,
+      });
+    });
+  }
+});
+
+// Find current page index in flattened items
+const currentIndex = flattenedItems.findIndex((item) => currentSlug === item.slug);
+
+// Get previous and next items
+const prevItem = currentIndex > 0 ? flattenedItems[currentIndex - 1] : null;
+const nextItem = currentIndex < flattenedItems.length - 1 ? flattenedItems[currentIndex + 1] : null;
+
+const ownersRaw = doc?.owners || [];
+const owners = await Promise.all<ReturnType<typeof getOwner>>(ownersRaw.map(getOwner));
+const filteredOwners = owners.filter((o) => o !== undefined);
+
+const ownersList = filteredOwners.map((o) => ({
+  label: o.data.name,
+  type: o.collection,
+  badge: o.collection === 'users' ? o.data.role : 'Team',
+  avatarUrl: o.collection === 'users' ? o.data.avatarUrl : '',
+  href: buildUrl(`/docs/${o.collection}/${o.data.id}`),
+}));
+
+const badges = doc?.badges || [];
+---
+
+<VerticalSideBarLayout title={doc.title || 'Documentation'}>
+  <div class="flex w-full">
+    <!-- Left Sidebar Navigation -->
+    <aside class="sidebar-transition overflow-y-auto bg-white border-r border-gray-100 w-80 fixed top-16 bottom-0 z-10">
+      <CustomDocsNav />
+    </aside>
+
+    <!-- Main Content Area - Independent scrolling -->
+    <main class="sidebar-transition w-full max-h-content ml-[22em] 2xl:ml-[24em] mr-80 lg:mr-[26em] max-w-5xl mx-auto">
+      <div class="max-w-7xl mx-auto px-6 py-10">
+        <div class="border-b border-gray-200 flex justify-between items-start md:pb-6">
+          <div>
+            <h2 id="doc-page-header" class="text-2xl md:text-4xl font-bold text-black">{doc.title}</h2>
+            {
+              badges && (
+                <div class="flex flex-wrap pt-4">
+                  {badges.map((badge: any) => {
+                    return (
+                      <a href={badge.url || '#'} class="pb-2">
+                        <span
+                          id={badge.id || ''}
+                          class={`text-sm font-light text-gray-500 px-2 py-1 rounded-md mr-2  bg-gradient-to-b  from-${badge.backgroundColor}-100 to-${badge.backgroundColor}-200 space-x-1 border border-${badge.backgroundColor}-200 text-${badge.textColor}-800 flex items-center ${badge.class ? badge.class : ''} `}
+                        >
+                          {badge.icon && <badge.icon className="w-4 h-4 inline-block mr-1 " />}
+                          {badge.iconURL && <img src={badge.iconURL} class="w-5 h-5 inline-block " />}
+                          <span>{badge.content}</span>
+                        </span>
+                      </a>
+                    );
+                  })}
+                </div>
+              )
+            }
+          </div>
+        </div>
+        <div class="flex-auto prose py-8 max-w-none">
+          <Content components={{ ...mdxComponents(props) }} />
+        </div>
+
+        <!-- Previous / Next Navigation -->
+        <div class="py-8 border-t border-gray-200 mt-8">
+          <div class="flex flex-col sm:flex-row justify-between w-full gap-4">
+            {
+              prevItem && (
+                <a
+                  href={buildUrl(`/docs/custom/${prevItem.slug}`)}
+                  class="group flex flex-col border border-gray-200 rounded-lg p-4 hover:border-gray-300 hover:bg-gray-50 transition-colors w-full sm:w-1/2"
+                >
+                  <span class="text-sm text-gray-500 mb-1">Previous</span>
+                  <span class="font-medium group-hover:text-primary-600 transition-colors">{prevItem.label}</span>
+                </a>
+              )
+            }
+
+            {!prevItem && <div class="w-full sm:w-1/2" />}
+
+            {
+              nextItem && (
+                <a
+                  href={buildUrl(`/docs/custom/${nextItem.slug}`)}
+                  class="group flex flex-col items-end text-right border border-gray-200 rounded-lg p-4 hover:border-gray-300 hover:bg-gray-50 transition-colors w-full sm:w-1/2"
+                >
+                  <span class="text-sm text-gray-500 mb-1">Next</span>
+                  <span class="font-medium group-hover:text-primary-600 transition-colors">{nextItem.label}</span>
+                </a>
+              )
+            }
+          </div>
+        </div>
+      </div>
+    </main>
+
+    <!-- Right Sidebar TOC -->
+    <aside
+      class="fixed right-0 top-16 bottom-0 w-96 overflow-y-auto border-l border-gray-100 bg-white p-6 flex-shrink-0 hidden lg:block z-10"
+    >
+      <div>
+        <div>
+          {
+            ownersList.length > 0 && (
+              <OwnersList
+                title={`Document Owners (${ownersList.length})`}
+                emptyMessage={`This page does not have any documented owners.`}
+                owners={ownersList}
+                client:load
+              />
+            )
+          }
+        </div>
+        <h3 class="text-sm text-black font-semibold group-data-[hover]:text-black/80 capitalize flex items-center gap-2">
+          <AlignLeftIcon className="w-4 h-4" />
+          On this page
+        </h3>
+        <nav class="space-y-1 text-sm py-4">
+          {
+            headings.map((heading) => {
+              if (heading.depth > 3) {
+                return null;
+              }
+              return (
+                <a
+                  href={`#${heading.slug}`}
+                  class={`block text-[12px] py-0.5 ${heading.depth === 1 ? 'font-light' : ''} text-gray-400 hover:text-primary-600`}
+                  style={`padding-left: ${(heading.depth - 1) * 8}px`}
+                >
+                  {heading.text}
+                </a>
+              );
+            })
+          }
+        </nav>
+      </div>
+    </aside>
+  </div>
+</VerticalSideBarLayout>
+
+<style is:global>
+  .mermaid svg {
+    margin: 1em auto 2em;
+  }
+
+  /* Fix for architecture diagrams */
+  .mermaid[data-content*='architecture'] svg {
+    max-width: 350px !important;
+    margin: 0;
+    /* width: 100px !important; */
+  }
+</style>
+
+<script define:vars={{ props, config }}>
+  // Fix to pass information to componets that are client side only
+  // and require catalog information
+  window.eventcatalog = {};
+  // @ts-ignore
+
+  window.eventcatalog.mermaid = config.mermaid;
+</script>
+
+<script>
+  // @ts-nocheck
+  function setupObserver() {
+    try {
+      const observerOptions = {
+        rootMargin: '0px 0px -40% 0px',
+        threshold: 0.1,
+      };
+
+      // Flag to temporarily disable observer after click
+      let observerPaused = false;
+
+      // Function to highlight a TOC item
+      function highlightTocItem(id) {
+        // Remove active class from all links
+        document.querySelectorAll('.active-toc-item').forEach((link) => {
+          link.classList.remove('active-toc-item', 'text-purple-600', 'font-light');
+          link.classList.add('text-gray-400');
+        });
+
+        // Add active class to current link
+        const tocLink = document.querySelector(`nav a[href="#${id}"]`);
+        if (tocLink) {
+          tocLink.classList.add('active-toc-item', 'text-purple-600', 'font-light');
+          tocLink.classList.remove('text-gray-400');
+
+          // Scroll the highlighted item into view with a small delay to ensure DOM updates first
+          setTimeout(() => {
+            tocLink.scrollIntoView({ behavior: 'smooth', block: 'nearest', inline: 'nearest' });
+          }, 10);
+        }
+      }
+
+      // Set up the intersection observer for scrolling
+      const observer = new IntersectionObserver((entries) => {
+        // If observer is paused, don't process entries
+        if (observerPaused) return;
+
+        entries.forEach((entry) => {
+          try {
+            const id = entry.target.getAttribute('id');
+            if (entry.isIntersecting && id) {
+              highlightTocItem(id);
+            }
+          } catch (entryError) {
+            console.error('Error processing intersection entry:', entryError);
+          }
+        });
+      }, observerOptions);
+
+      // Find all headings in the content area within the .prose container to observe
+      const prose = document.querySelector('.prose');
+      if (!prose) {
+        console.warn('No .prose container found for TOC highlighting');
+        return;
+      }
+
+      // First try to find headings with IDs
+      const headings = prose.querySelectorAll('h1[id], h2[id], h3[id]');
+      console.log('Headings with IDs found:', headings.length);
+
+      if (headings.length > 0) {
+        headings.forEach((heading) => {
+          observer.observe(heading);
+        });
+      } else {
+        // Fallback: If no headings with IDs found, attach IDs to them
+        const allHeadings = prose.querySelectorAll('h1, h2, h3');
+        console.log('Total headings found:', allHeadings.length);
+
+        allHeadings.forEach((heading) => {
+          // Only add ID if it doesn't exist
+          if (!heading.id) {
+            const text = heading.textContent || '';
+            const slug = text
+              .toLowerCase()
+              .replace(/[^\w\s-]/g, '')
+              .replace(/\s+/g, '-');
+            heading.id = slug;
+          }
+          observer.observe(heading);
+        });
+      }
+
+      // Add click event listeners to all TOC links
+      const tocLinks = document.querySelectorAll('nav a[href^="#"]');
+      tocLinks.forEach((link) => {
+        link.addEventListener('click', (e) => {
+          // Get the ID from the href attribute
+          const hrefAttr = link.getAttribute('href');
+          if (!hrefAttr) return;
+
+          const id = hrefAttr.substring(1);
+
+          // Highlight the clicked item
+          highlightTocItem(id);
+
+          // Temporarily pause the observer to prevent immediate highlighting changes
+          observerPaused = true;
+
+          // Resume the observer after a delay (1.5 seconds)
+          setTimeout(() => {
+            observerPaused = false;
+          }, 500);
+        });
+      });
+    } catch (error) {
+      console.error('Error setting up TOC highlighting:', error);
+    }
+  }
+
+  setupObserver();
+
+  document.addEventListener('astro:page-load', () => {
+    const graphs = document.getElementsByClassName('mermaid');
+    if (document.getElementsByClassName('mermaid').length > 0) {
+      renderDiagrams(graphs);
+    }
+  });
+
+  async function renderDiagrams(graphs: any) {
+    const { default: mermaid } = await import('mermaid');
+
+    if (window.eventcatalog.mermaid) {
+      const { icons } = await import('@iconify-json/logos');
+      const { iconPacks = [] } = window.eventcatalog.mermaid ?? {};
+
+      if (iconPacks.length > 0) {
+        const iconPacksToRegister = iconPacks.map((name: string) => {
+          return {
+            name,
+            icons,
+          };
+        });
+
+        mermaid.registerIconPacks(iconPacksToRegister);
+      }
+    }
+
+    mermaid.initialize({
+      // fontSize: 2,
+      flowchart: {
+        curve: 'linear',
+        rankSpacing: 0,
+        nodeSpacing: 0,
+      },
+      startOnLoad: false,
+      fontFamily: 'var(--sans-font)',
+      // @ts-ignore This works, but TS expects a enum for some reason
+      theme: 'light',
+      architecture: {
+        useMaxWidth: true,
+      },
+    });
+
+    for (const graph of graphs) {
+      const content = graph.getAttribute('data-content');
+      if (!content) continue;
+      let svg = document.createElement('svg');
+      const id = (svg.id = 'mermaid-' + Math.round(Math.random() * 100000));
+      graph.appendChild(svg);
+      mermaid.render(id, content).then((result) => {
+        graph.innerHTML = result.svg;
+      });
+    }
+  }
+
+  const graphs = document.getElementsByClassName('mermaid');
+  if (document.getElementsByClassName('mermaid').length > 0) {
+    renderDiagrams(graphs);
+  }
+
+  document.addEventListener('astro:page-load', setupObserver);
+</script>

package/eventcatalog/src/enterprise/custom-documentation/utils/custom-docs.ts

@@ -0,0 +1,118 @@
+// import { getCollection } from "astro:content";
+import config from '@config';
+import fs from 'node:fs';
+import path from 'node:path';
+import { getEntry } from 'astro:content';
+import matter from 'gray-matter';
+
+type Badge = {
+  text: string;
+  color: string;
+};
+
+type SidebarItem = {
+  label: string;
+  slug?: string;
+  items?: SidebarItem[];
+  badge?: Badge;
+  collapsed?: boolean;
+};
+
+type SideBarConfigurationItem = {
+  label: string;
+  items?: SidebarItem[];
+  slug?: string;
+  autogenerated?: {
+    directory: string;
+  };
+  badge?: Badge;
+  collapsed?: boolean;
+};
+
+const DOCS_DIR = 'docs';
+
+/**
+ * Processes auto-generated directory and returns navigation items
+ */
+const processAutoGeneratedDirectory = async (
+  directory: string,
+  label: string,
+  badge?: Badge,
+  collapsed?: boolean
+): Promise<SidebarItem> => {
+  // @ts-ignore
+  const files = fs.readdirSync(path.join(process.env.PROJECT_DIR || '', DOCS_DIR, directory));
+
+  // Convert files to frontmatter
+  const docsWithFrontmatter = files.map((file) => {
+    // @ts-ignore
+    const content = fs.readFileSync(path.join(process.env.PROJECT_DIR || '', DOCS_DIR, directory, file), 'utf8');
+    const { data } = matter(content);
+    return { ...data, file };
+  });
+
+  // If user defined slug use it, otherwise use the file
+  const astroIdsForFiles = docsWithFrontmatter.map(
+    (doc: any) => doc.slug || path.join(DOCS_DIR, directory, doc.file).replace('.mdx', '')
+  );
+
+  const entries = await Promise.all(
+    astroIdsForFiles.map(async (astroId) => {
+      const entry = await getEntry('customPages', astroId);
+      return entry;
+    })
+  );
+
+  // Filter anything we haven't found
+  const filteredEntries = entries.filter((entry) => entry !== undefined);
+
+  return {
+    label,
+    items: filteredEntries.map((entry) => ({
+      label: entry?.data?.title,
+      slug: entry?.data?.slug || entry?.id.replace(DOCS_DIR, ''),
+    })),
+  };
+};
+
+/**
+ * Recursively process sidebar items to handle auto-generated content at any nesting level
+ */
+const processSidebarItems = async (items: SideBarConfigurationItem[]): Promise<SidebarItem[]> => {
+  const processedItems: SidebarItem[] = [];
+
+  for (const item of items) {
+    // If item has autogenerated property, process it
+    if (item.autogenerated) {
+      const processedItem = await processAutoGeneratedDirectory(
+        item.autogenerated.directory,
+        item.label,
+        item.badge,
+        item.collapsed
+      );
+      processedItems.push(processedItem);
+    }
+    // If item has nested items, process them recursively
+    else if (item.items && item.items.length > 0) {
+      const processedNestedItems = await processSidebarItems(item.items as SideBarConfigurationItem[]);
+      processedItems.push({
+        label: item.label,
+        slug: item.slug,
+        items: processedNestedItems,
+        badge: item.badge,
+        collapsed: item.collapsed,
+      });
+    }
+    // Otherwise, it's a regular item
+    else {
+      processedItems.push(item as SidebarItem);
+    }
+  }
+
+  return processedItems;
+};
+
+export const getNavigationItems = async (): Promise<SidebarItem[]> => {
+  const configuredSidebar = config.customDocs.sidebar;
+  return processSidebarItems(configuredSidebar as SideBarConfigurationItem[]);
+};

package/eventcatalog/src/layouts/VerticalSideBarLayout.astro

@@ -5,12 +5,25 @@ interface Props {
   description?: string;
 }
 
-import { BookOpenText, Workflow, TableProperties, House, BookUser, MessageSquare, BotMessageSquare, Users } from 'lucide-react';
+import {
+  BookOpenText,
+  BookText,
+  Workflow,
+  TableProperties,
+  House,
+  BookUser,
+  MessageSquare,
+  BotMessageSquare,
+  Users,
+  Star,
+  BadgeCheck,
+  Sparkles,
+} from 'lucide-react';
 import Header from '../components/Header.astro';
 import SEO from '../components/Seo.astro';
 import SideNav from '../components/SideNav/SideNav.astro';
 import config from '@config';
-
+import { getCollection } from 'astro:content';
 import '@fontsource/inter';
 import '@fontsource/inter/400.css'; // Specify weight
 import '@fontsource/inter/700.css'; // Specify weight
@@ -24,19 +37,24 @@ import { isCollectionVisibleInCatalog } from '@eventcatalog';
 import { buildUrl } from '@utils/url-builder';
 import { getQueries } from '@utils/queries';
 import { hasLandingPageForDocs } from '@utils/pages';
-
+import { isEventCatalogProEnabled } from '@utils/feature';
 const events = await getEvents({ getAllVersions: false });
 const commands = await getCommands({ getAllVersions: false });
 const queries = await getQueries({ getAllVersions: false });
 const services = await getServices({ getAllVersions: false });
 const domains = await getDomains({ getAllVersions: false });
 const flows = await getFlows({ getAllVersions: false });
+const customDocs = await getCollection('customPages');
 
 const currentPath = Astro.url.pathname;
 
 const catalogHasDefaultLandingPageForDocs = await hasLandingPageForDocs();
 
 const getDefaultUrl = (route: string, defaultValue: string) => {
+  if (route === 'docs/custom') {
+    return customDocs.length > 0 ? buildUrl(`/${route}/${customDocs[0].id.replace('docs', '')}`) : buildUrl(defaultValue);
+  }
+
   const collections = [
     { data: domains, key: 'domains' },
     { data: services, key: 'services' },
@@ -68,12 +86,22 @@ const navigationItems = [
   },
   {
     id: '/docs',
-    label: 'Documentation',
+    label: 'Architecture Documentation',
     icon: BookOpenText,
     href: catalogHasDefaultLandingPageForDocs ? buildUrl('/docs') : getDefaultUrl('docs', '/docs'),
-    current: currentPath.includes('/docs') || currentPath.includes('/architecture/docs/'),
+    current:
+      (currentPath.includes('/docs') && !currentPath.includes('/docs/custom')) || currentPath.includes('/architecture/docs/'),
     sidebar: true,
   },
+  {
+    id: '/docs/custom',
+    label: 'Documentation',
+    icon: BookText,
+    href: getDefaultUrl('docs/custom', '/docs/custom'),
+    current: currentPath.includes('/docs/custom'),
+    sidebar: false,
+    hidden: !isEventCatalogProEnabled(),
+  },
   {
     id: '/visualiser',
     label: 'Visualiser',
@@ -131,7 +159,7 @@ const canPageBeEmbedded = process.env.ENABLE_EMBED === 'true';
 <html lang="en">
   <head>
     <SEO title={`EventCatalog | ${title}`} description={description} ogTitle={title} />
-    <style>
+    <style is:global>
       .sidebar-transition {
         transition-property: width, transform;
         transition-duration: 300ms;
@@ -154,7 +182,7 @@ const canPageBeEmbedded = process.env.ENABLE_EMBED === 'true';
         <div
           class="fixed flex flex-col items-center w-16 h-screen py-4 bg-white bg-gradient-to-b from-white to-gray-100 border-r border-gray-200 z-20 shadow-md justify-between"
         >
-          <nav class="flex flex-col h-[84vh] justify-between">
+          <nav class="flex flex-col h-[calc(100vh-70px)] justify-between">
             <div class="flex flex-col items-center flex-1 space-y-8">
               {
                 navigationItems
@@ -178,6 +206,25 @@ const canPageBeEmbedded = process.env.ENABLE_EMBED === 'true';
                   })
               }
             </div>
+
+            {/* Pro link at the bottom */}
+            <div class="mb-4">
+              <a
+                id="/pro"
+                data-role="nav-item"
+                href={buildUrl('/pro')}
+                class={`p-1.5 inline-block transition-colors duration-200 rounded-lg ${currentPath.includes('/pro') ? 'text-white bg-gradient-to-b from-purple-500 to-purple-700' : 'bg-gradient-to-r from-purple-100 to-indigo-100 hover:from-purple-500 hover:to-purple-700 hover:text-white text-purple-700'}`}
+              >
+                <div class="has-tooltip">
+                  <span
+                    class="tooltip rounded shadow-lg p-1 text-xs bg-gradient-to-l from-purple-500 to-purple-700 text-white ml-10"
+                  >
+                    EventCatalog Pro
+                  </span>
+                  <Sparkles className="h-6 w-6" />
+                </div>
+              </a>
+            </div>
           </nav>
         </div>
 
@@ -193,7 +240,7 @@ const canPageBeEmbedded = process.env.ENABLE_EMBED === 'true';
         <slot />
       </main>
 
-      <!-- Creae a overlay that tells people to purchase backstage plugin if they want to embed the page -->
+      <!-- Create a overlay that tells people to purchase backstage plugin if they want to embed the page -->
       <div class="absolute inset-0 bg-black items-center justify-center z-50 hidden" id="embed-overlay">
         <div class="text-white text-center space-y-4">
           <div>
@@ -259,7 +306,7 @@ const canPageBeEmbedded = process.env.ENABLE_EMBED === 'true';
     const currentPath = window.location.href;
 
     // Hide the sidebar if the current navigation item is not a sidebar item
-    if (!currentNavigationItem.sidebar) {
+    if (!currentNavigationItem?.sidebar) {
       sidebar.style.display = 'none';
       content.style.width = '100%';
       content.classList.add('ml-16');
@@ -277,7 +324,7 @@ const canPageBeEmbedded = process.env.ENABLE_EMBED === 'true';
 
         const navItem = navigationItems.find((navItem) => navItem.id === id);
 
-        if (!navItem.sidebar || !currentPath.includes(navItem.id)) {
+        if (!navItem.sidebar || !currentPath.includes(navItem.id) || currentPath.includes('/docs/custom')) {
           window.location.href = navItem.href;
           return;
         }