@eventcatalog/core 4.9.0 → 4.10.1

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">

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

@@ -19,6 +19,11 @@ const pageTitle = `${props.collection} | ${props.data.name}`.replace(/^\w/, (c)
 const ubiquitousLanguageData = await getUbiquitousLanguageWithSubdomains(props);
 const ubiquitousLanguage = ubiquitousLanguageData.domain;
 const { subdomains, duplicateTerms } = ubiquitousLanguageData;
+
+const termCount =
+  (ubiquitousLanguage?.data.dictionary?.length ?? 0) +
+  subdomains.reduce((total, subdomain: any) => total + (subdomain.ubiquitousLanguage?.data.dictionary?.length ?? 0), 0);
+const ownerTypeLabel = props.collection === 'domains' ? 'Domain' : 'System';
 ---
 
 <VerticalSideBarLayout title={pageTitle} description={props.data.summary}>
@@ -28,26 +33,31 @@ const { subdomains, duplicateTerms } = ubiquitousLanguageData;
     data-pagefind-meta={`title:${pageTitle}`}
   >
     <div class="flex docs-layout w-full">
-      <div class="w-full lg:mr-2 pr-24 py-8 min-h-[50em]">
-        {/* Title Section */}
-        <div class="relative border-b border-[rgb(var(--ec-page-border))] mb-6 pb-6">
-          <div class="xl:flex xl:items-start xl:justify-between">
-            <div class="min-w-0 flex-1">
-              <h1 class="text-2xl md:text-4xl font-bold text-[rgb(var(--ec-page-text))]">Ubiquitous Language</h1>
-              <p class="pt-2 text-base text-[rgb(var(--ec-page-text-muted))] font-light">
-                Browse and discover ubiquitous language terms in the {props.data.name} domain{
-                  subdomains.length > 0 ? ' and its subdomains' : ''
-                }
-              </p>
-            </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">{ownerTypeLabel}</span>
+            <h1 id="doc-page-header" class="text-2xl md:text-4xl font-bold text-[rgb(var(--ec-page-text))]">
+              Ubiquitous Language
+            </h1>
+          </div>
+          <p class="text-base pt-4 pb-1 text-[rgb(var(--ec-page-text-muted))] font-light">
+            {termCount} {termCount === 1 ? 'term' : 'terms'} used in the {props.data.name} {ownerTypeLabel.toLowerCase()}{
+              subdomains.length > 0 ? ' and its subdomains' : ''
+            }.
+          </p>
+        </div>
 
-            <div class="mt-4 xl:mt-0 xl:ml-4 xl:flex-shrink-0">
-              <div class="relative w-full xl:w-80">
+        {
+          !ubiquitousLanguage && termCount > 0 && (
+            <div class="pt-8">
+              <div class="relative w-full max-w-md">
                 <input
                   type="text"
                   id="searchInput"
                   placeholder="Search terms..."
-                  class="block w-full rounded-md border-0 py-1.5 pr-4 pl-10 text-sm font-light text-[rgb(var(--ec-header-text))] bg-[rgb(var(--ec-header-bg))] shadow-xs ring-1 ring-inset ring-[rgb(var(--ec-dropdown-border))] placeholder:text-[rgb(var(--ec-icon-color))] focus:ring-2 focus:ring-[rgb(var(--ec-accent))] focus:outline-none"
+                  class="block w-full rounded-md border-0 py-2 pr-4 pl-10 text-sm font-light text-[rgb(var(--ec-header-text))] bg-[rgb(var(--ec-header-bg))] shadow-xs ring-1 ring-inset ring-[rgb(var(--ec-dropdown-border))] placeholder:text-[rgb(var(--ec-icon-color))] focus:ring-2 focus:ring-[rgb(var(--ec-accent))] focus:outline-none"
                 />
                 <div class="absolute inset-y-0 left-0 pl-3 flex items-center pointer-events-none">
                   <svg class="h-4 w-4 text-[rgb(var(--ec-icon-color))]" fill="none" stroke="currentColor" viewBox="0 0 24 24">
@@ -60,8 +70,8 @@ const { subdomains, duplicateTerms } = ubiquitousLanguageData;
                 </div>
               </div>
             </div>
-          </div>
-        </div>
+          )
+        }
 
         {
           !ubiquitousLanguage && subdomains.length === 0 && (
@@ -82,7 +92,7 @@ const { subdomains, duplicateTerms } = ubiquitousLanguageData;
           )
         }
 
-        <div class="py-4 w-full min-h-[calc(100vh-10em)]">
+        <div class="pt-8 pb-4 w-full min-h-[calc(100vh-10em)]">
           {
             (ubiquitousLanguage || subdomains.some((s) => s.ubiquitousLanguage)) && (
               <div>
@@ -101,6 +111,23 @@ const { subdomains, duplicateTerms } = ubiquitousLanguageData;
                           </span>
                         </h3>
                       </div>
+                      <div class="relative w-64 flex-shrink-0">
+                        <input
+                          type="text"
+                          id="searchInput"
+                          placeholder="Search terms..."
+                          class="block w-full rounded-md border-0 py-1.5 pr-4 pl-9 text-sm font-light text-[rgb(var(--ec-header-text))] bg-[rgb(var(--ec-header-bg))] shadow-xs ring-1 ring-inset ring-[rgb(var(--ec-dropdown-border))] placeholder:text-[rgb(var(--ec-icon-color))] focus:ring-2 focus:ring-[rgb(var(--ec-accent))] focus:outline-none"
+                        />
+                        <div class="absolute inset-y-0 left-0 pl-3 flex items-center pointer-events-none">
+                          <svg class="h-4 w-4 text-[rgb(var(--ec-icon-color))]" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                            <path
+                              stroke-linecap="round"
+                              stroke-linejoin="round"
+                              stroke-width="2"
+                              d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z"></path>
+                          </svg>
+                        </div>
+                      </div>
                     </div>
                     <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4" data-terms-grid="main">
                       {ubiquitousLanguage?.data?.dictionary?.map((term) => (

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

@@ -103,7 +103,7 @@ const sourceTitle = sourceLabel ? `Synced from ${sourceLabel}` : undefined;
     data-pagefind-meta={`title:${pageTitle}`}
   >
     <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))] pb-6">
           <div class="flex justify-start">
             <div class="flex flex-col justify-between space-y-3">

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

@@ -100,7 +100,7 @@ const sourceTitle = sourceLabel ? `Synced from ${sourceLabel}` : undefined;
     data-pagefind-meta={`title:${pageTitle}`}
   >
     <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))] pb-6">
           <div class="flex justify-start gap-6">
             {

package/eventcatalog/src/pages/index.astro

@@ -1,16 +1,19 @@
 ---
 import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
-import { getMDXComponentsByName } from '@utils/markdown';
+import { getMDXComponentsByName, parseMdxBooleanProp } from '@utils/markdown';
+import { architectureGraphPortalId } from '@components/MDX/ArchitectureGraph/ArchitectureGraphPortal';
 import { resourceToCollectionMap } from '@utils/collections/util';
 import { buildUrl } from '@utils/url-builder';
-import { isCustomLandingPageEnabled, isVisualiserEnabled } from '@utils/feature';
+import { isCustomLandingPageEnabled, isVisualiserEnabled, isArchitectureGraphEnabled } from '@utils/feature';
 import DefaultAstroLandingPage from './_index.astro';
 import config from '@config';
 
 let nodeGraphs: any[] = [];
 let systemContextMaps: any[] = [];
+let architectureGraphs: any[] = [];
 let CustomContent = null;
 let NodeGraph = null;
+let ArchitectureGraph = null;
 let customHomepageComponents: Record<string, any> = {};
 
 import path from 'path';
@@ -37,11 +40,19 @@ if (existsSync(pathToUserDefinedLandingPage) && isCustomLandingPageEnabled()) {
   // The homepage can also embed the global System Context Map via <SystemContextMap />.
   systemContextMaps = getMDXComponentsByName(rawContent, 'SystemContextMap') || [];
 
+  // …and the catalog-wide Architecture Graph via <ArchitectureGraph />. With no
+  // `id` + `type` the whole catalog is rendered.
+  architectureGraphs = getMDXComponentsByName(rawContent, 'ArchitectureGraph') || [];
+
   // Avoid pulling visualizer CSS into the default homepage bundle.
   // Only load the NodeGraph component when the custom homepage actually uses a graph.
   if (nodeGraphs.length > 0 || systemContextMaps.length > 0) {
     NodeGraph = (await import('@components/MDX/NodeGraph/NodeGraph.astro')).default;
   }
+  // Only build the catalog-wide graph data when the homepage actually embeds it.
+  if (architectureGraphs.length > 0) {
+    ArchitectureGraph = (await import('@components/MDX/ArchitectureGraph/ArchitectureGraph.astro')).default;
+  }
 }
 
 if (config.landingPage) {
@@ -104,6 +115,27 @@ if (config.landingPage) {
               }
             />
           ))}
+        {ArchitectureGraph &&
+          architectureGraphs.map((graph: any, occurrenceIndex: number) => (
+            <ArchitectureGraph
+              id={graph.id}
+              collection={graph.type ? resourceToCollectionMap[graph.type as keyof typeof resourceToCollectionMap] : undefined}
+              depth={graph.depth ? Number(graph.depth) : undefined}
+              lens={graph.lens}
+              showSearch={parseMdxBooleanProp(graph.search, true)}
+              showLegend={parseMdxBooleanProp(graph.legend, true)}
+              showLensPicker={parseMdxBooleanProp(graph.lensPicker, false)}
+              portalId={architectureGraphPortalId(graph.id, occurrenceIndex)}
+              href={
+                isArchitectureGraphEnabled()
+                  ? {
+                      label: 'Open full screen',
+                      url: buildUrl('/visualiser/graph'),
+                    }
+                  : undefined
+              }
+            />
+          ))}
       </main>
     </VerticalSideBarLayout>
   ) : (

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

@@ -130,7 +130,11 @@ const apiAccessEnabled = isEventCatalogScaleEnabled();
 ---
 
 <VerticalSideBarLayout title={pageTitle}>
-  <div class="h-[calc(100vh-4rem)] w-full overflow-hidden flex flex-col">
+  {/* The schema viewer is an app-style surface: pull it out of the content gutter so it sits flush against the sidebar. */}
+  <div
+    class="h-[calc(100vh-4rem)] overflow-hidden 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);"
+  >
     {
       currentMessage ? (
         <SchemaPageViewer

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

@@ -3,6 +3,8 @@ import { getCollection, type CollectionEntry } from 'astro:content';
 
 import LineageScenarioSwitcher from '@components/Lineage/LineageScenarioSwitcher';
 import AstroNodeGraph from '@components/MDX/NodeGraph/AstroNodeGraph';
+// Visualiser styles ship in the page head so ClientRouter navigations keep them (see NodeGraph.astro).
+import '@eventcatalog/visualiser/styles-core.css';
 import ResourceRef from '@components/MDX/ResourceRef/ResourceRef.astro';
 import Footer from '@layouts/Footer.astro';
 import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';

package/eventcatalog/src/pages/visualiser/designs/[id]/index.astro

@@ -1,5 +1,7 @@
 ---
 import AstroNodeGraph from '@components/MDX/NodeGraph/AstroNodeGraph';
+// Visualiser styles ship in the page head so ClientRouter navigations keep them (see NodeGraph.astro).
+import '@eventcatalog/visualiser/styles-core.css';
 import { ClientRouter } from 'astro:transitions';
 import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
 import { isEventCatalogChatEnabled } from '@utils/feature';

package/eventcatalog/src/pages/visualiser/graph/index.astro

@@ -1,8 +1,7 @@
 ---
 import VisualiserLayout from '@layouts/VisualiserLayout.astro';
 import CatalogForceGraph from '@components/CatalogGraph/CatalogForceGraph';
-import type { CatalogGraphWireLink } from '@components/CatalogGraph/CatalogForceGraph';
-import { getCatalogForceGraph } from '@utils/node-graphs/catalog-force-graph';
+import { getCatalogForceGraph, toCatalogForceGraphWire } from '@utils/node-graphs/catalog-force-graph';
 import { isArchitectureGraphEnabled } from '@utils/feature';
 
 // Bail before building the graph — on very large catalogs the whole point of
@@ -11,29 +10,9 @@ if (!isArchitectureGraphEnabled()) {
   return new Response(null, { status: 404 });
 }
 
-const { nodes, links } = await getCatalogForceGraph();
-
 // Compact wire format: index-based links and client-derived URLs keep the
 // island props Astro serialises into the page small for large catalogs.
-const nodeIndexById = new Map(nodes.map((node, index) => [node.id, index]));
-const linkLabels = [...new Set(links.map((link) => link.label))];
-const labelIndexByLabel = new Map(linkLabels.map((label, index) => [label, index]));
-
-const wireNodes = nodes.map(({ id, label, collection, version }) => ({
-  // Node ids are `${collection}/${resourceId}` — send only the resource id, the client rebuilds the key
-  id: id.slice(collection.length + 1),
-  label,
-  collection,
-  version,
-}));
-
-const wireLinks = links.map(
-  (link): CatalogGraphWireLink => [
-    nodeIndexById.get(link.source)!,
-    nodeIndexById.get(link.target)!,
-    labelIndexByLabel.get(link.label)!,
-  ]
-);
+const { nodes: wireNodes, links: wireLinks, linkLabels } = toCatalogForceGraphWire(await getCatalogForceGraph());
 ---
 
 <VisualiserLayout title="Visualiser | Architecture Graph" description="Force-directed graph of every resource in the catalog">

package/eventcatalog/src/stores/sidebar-store/builders/adr.ts

@@ -8,7 +8,7 @@ import {
   type AdrResource,
 } from '@utils/collections/adrs';
 import { collectionToResourceMap, createVersionedMap, findInMap } from '@utils/collections/util';
-import type { ChildRef, NavNode, ResourceGroupContext } from './shared';
+import type { NavNode, ResourceGroupContext } from './shared';
 import {
   buildAttachmentsSection,
   buildOwnersSection,
@@ -17,6 +17,7 @@ import {
   shouldRenderSideBarSection,
 } from './shared';
 import { isChangelogEnabled } from '@utils/feature';
+import { resolveSidebarPages, toCustomSidebarContext, type SidebarSpec } from '../custom-sidebar';
 
 const firstClassResourceCollections = [
   'agents',
@@ -102,13 +103,105 @@ const buildDecisionMakersSection = (decisionMakers: any[]): NavNode | null => {
   };
 };
 
-export const buildAdrNode = (adr: Adr, owners: any[], decisionMakers: any[], context: ResourceGroupContext): NavNode => {
+/**
+ * Predefined sidebar sections for a decision record, keyed by the token users reference from
+ * `sidebar.json` (e.g. `$quick-reference`). Each token is the kebab-cased title of the
+ * section as it appears in the default sidebar.
+ */
+export type AdrSectionKey =
+  | 'quick-reference'
+  | 'applies-to'
+  | 'supersedes'
+  | 'superseded-by'
+  | 'amends'
+  | 'amended-by'
+  | 'related-decisions'
+  | 'decision-makers'
+  | 'owners'
+  | 'code'
+  | 'attachments';
+
+export type AdrSections = Record<AdrSectionKey, NavNode | NavNode[] | null>;
+
+/** Order of sections in the default (generated) sidebar. */
+export const DEFAULT_ADR_SECTION_ORDER: AdrSectionKey[] = [
+  'quick-reference',
+  'applies-to',
+  'supersedes',
+  'superseded-by',
+  'amends',
+  'amended-by',
+  'related-decisions',
+  'decision-makers',
+  'owners',
+  'code',
+  'attachments',
+];
+
+export const buildAdrSections = (adr: Adr, owners: any[], decisionMakers: any[], context: ResourceGroupContext): AdrSections => {
   const relationships = getAdrRelationships(adr, context.adrs);
   const appliesToRefs = resolveAppliedResourceRefs(adr, context);
   const hasAttachments = adr.data.attachments && adr.data.attachments.length > 0;
   const renderOwners = owners.length > 0 && shouldRenderSideBarSection(adr, 'owners');
   const renderDecisionMakers = decisionMakers.length > 0 && shouldRenderSideBarSection(adr, 'decisionMakers');
   const renderRepository = adr.data.repository && shouldRenderSideBarSection(adr, 'repository');
+  const renderRelationships = shouldRenderSideBarSection(adr, 'relationships');
+
+  return {
+    'quick-reference': buildQuickReferenceSection(
+      [
+        { title: 'Overview', href: buildUrl(`/docs/adrs/${adr.data.id}/${adr.data.version}`) },
+        isChangelogEnabled() &&
+          shouldRenderSideBarSection(adr, 'changelog') && {
+            title: 'Changelog',
+            href: buildUrl(`/docs/adrs/${adr.data.id}/${adr.data.version}/changelog`),
+          },
+      ].filter(Boolean) as { title: string; href: string }[]
+    ),
+    'applies-to':
+      appliesToRefs.length > 0 && shouldRenderSideBarSection(adr, 'appliesTo')
+        ? {
+            type: 'group',
+            title: 'Applies to',
+            icon: 'GitBranch',
+            pages: appliesToRefs,
+          }
+        : null,
+    supersedes: renderRelationships ? buildAdrRelationshipSection('Supersedes', 'History', relationships.supersedes) : null,
+    'superseded-by': renderRelationships
+      ? buildAdrRelationshipSection('Superseded by', 'History', relationships.supersededBy)
+      : null,
+    amends: renderRelationships ? buildAdrRelationshipSection('Amends', 'Pencil', relationships.amends) : null,
+    'amended-by': renderRelationships ? buildAdrRelationshipSection('Amended by', 'Pencil', relationships.amendedBy) : null,
+    'related-decisions': renderRelationships
+      ? buildAdrRelationshipSection('Related decisions', 'Link', resolveAdrPointers(adr.data.related, context.adrs))
+      : null,
+    'decision-makers': renderDecisionMakers ? buildDecisionMakersSection(decisionMakers) : null,
+    owners: renderOwners ? buildOwnersSection(owners) : null,
+    code: renderRepository ? buildRepositorySection(adr.data.repository as { url: string; language: string }) : null,
+    attachments: hasAttachments ? buildAttachmentsSection(adr.data.attachments as any[]) : null,
+  };
+};
+
+export type BuildAdrNodeOptions = {
+  /** A parsed `sidebar.json` for this decision record. When present it replaces the generated sidebar. */
+  sidebar?: SidebarSpec;
+};
+
+export const buildAdrNode = (
+  adr: Adr,
+  owners: any[],
+  decisionMakers: any[],
+  context: ResourceGroupContext,
+  options: BuildAdrNodeOptions = {}
+): NavNode => {
+  const sections = buildAdrSections(adr, owners, decisionMakers, context);
+
+  const pages = resolveSidebarPages(sections, DEFAULT_ADR_SECTION_ORDER, {
+    sidebar: options.sidebar,
+    resource: { collection: 'adrs', id: adr.data.id, version: adr.data.version, entry: adr },
+    context: toCustomSidebarContext(context),
+  });
 
   return {
     type: 'item',
@@ -116,37 +209,6 @@ export const buildAdrNode = (adr: Adr, owners: any[], decisionMakers: any[], con
     badge: 'Decision record',
     summary: adr.data.summary,
     icon: 'ClipboardList',
-    pages: [
-      buildQuickReferenceSection(
-        [
-          { title: 'Overview', href: buildUrl(`/docs/adrs/${adr.data.id}/${adr.data.version}`) },
-          isChangelogEnabled() &&
-            shouldRenderSideBarSection(adr, 'changelog') && {
-              title: 'Changelog',
-              href: buildUrl(`/docs/adrs/${adr.data.id}/${adr.data.version}/changelog`),
-            },
-        ].filter(Boolean) as { title: string; href: string }[]
-      ),
-      appliesToRefs.length > 0 &&
-        shouldRenderSideBarSection(adr, 'appliesTo') && {
-          type: 'group',
-          title: 'Applies to',
-          icon: 'GitBranch',
-          pages: appliesToRefs,
-        },
-      shouldRenderSideBarSection(adr, 'relationships') &&
-        buildAdrRelationshipSection('Supersedes', 'History', relationships.supersedes),
-      shouldRenderSideBarSection(adr, 'relationships') &&
-        buildAdrRelationshipSection('Superseded by', 'History', relationships.supersededBy),
-      shouldRenderSideBarSection(adr, 'relationships') && buildAdrRelationshipSection('Amends', 'Pencil', relationships.amends),
-      shouldRenderSideBarSection(adr, 'relationships') &&
-        buildAdrRelationshipSection('Amended by', 'Pencil', relationships.amendedBy),
-      shouldRenderSideBarSection(adr, 'relationships') &&
-        buildAdrRelationshipSection('Related decisions', 'Link', resolveAdrPointers(adr.data.related, context.adrs)),
-      renderDecisionMakers && buildDecisionMakersSection(decisionMakers),
-      renderOwners && buildOwnersSection(owners),
-      renderRepository && buildRepositorySection(adr.data.repository as { url: string; language: string }),
-      hasAttachments && buildAttachmentsSection(adr.data.attachments as any[]),
-    ].filter(Boolean) as ChildRef[],
+    pages,
   };
 };