Add support for Mermaid diagrams rendering

This PR introduces the possibility to add mermaid diagrams directly as
code in the antora docs.

These diagrams are then rendered client-side in real time. They support
zooming and panning, making them really easy to view and navigate.

Support for mermaid will allow for easy integration of high level
conforma diagrams into our docs, that are easily versionable (as
opposed to embedding pre-rendered images generated by other tools)

Assisted by: Claude Code

Ref: https://issues.redhat.com/browse/EC-1270

Author: st3penta

antora/antora-playbook.yml

@@ -51,3 +51,4 @@ antora:
 asciidoc:
   extensions:
     - '@asciidoctor/tabs'
+    - './extensions/mermaid.js'

antora/extensions/mermaid.js

@@ -0,0 +1,18 @@
+function createMermaidExtension() {
+  return function () {
+    this.block('mermaid', function () {
+      const self = this
+      self.named('mermaid')
+      self.onContext('literal')
+      self.process(function (parent, reader) {
+        const source = reader.getLines().join('\n')
+        const html = `<div class="mermaid">
+${source}
+</div>`
+        return self.createBlock(parent, 'pass', html)
+      })
+    })
+  }
+}
+
+module.exports = createMermaidExtension()

antora/package-lock.json

@@ -24,6 +24,7 @@
   },
   "dependencies": {
     "@antora/lunr-extension": "^1.0.0-alpha.10",
-    "@asciidoctor/tabs": "^1.0.0-beta.6"
+    "@asciidoctor/tabs": "^1.0.0-beta.6",
+    "mermaid": "^11.10.1"
   }
 }

antora/package.json

@@ -0,0 +1,56 @@
+/* Mermaid diagram styling */
+.mermaid {
+  text-align: center;
+  padding: 0.5rem;
+  border: 1px solid #e1e5e9;
+  border-radius: 6px;
+  background-color: #ffffff;
+  overflow-x: auto;
+  cursor: zoom-in;
+  transition: box-shadow 0.2s ease;
+}
+
+.mermaid:hover {
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+}
+
+/* Make sure text in diagrams is readable */
+.mermaid span {
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+  font-size: 18px !important;
+}
+
+/* Ensure diagrams don't get cut off */
+.mermaid svg {
+  max-width: 100%;
+  height: auto;
+  display: block;
+}
+
+/* Zoom overlay styling */
+.mermaid-zoom-overlay {
+  backdrop-filter: blur(4px);
+}
+
+.mermaid-zoom-overlay .mermaid {
+  cursor: zoom-out;
+  border: none;
+  box-shadow: 0 10px 40px rgba(0, 0, 0, 0.3);
+  max-width: 95vw;
+  max-height: 95vh;
+  overflow: auto;
+}
+
+/* Responsive adjustments */
+@media (max-width: 768px) {
+  .mermaid {
+    padding: 0.5rem;
+    margin: 0.5rem 0;
+  }
+
+  .mermaid-zoom-overlay .mermaid {
+    max-width: 98vw;
+    max-height: 98vh;
+    padding: 10px;
+  }
+}

antora/supplemental-ui/css/mermaid.css

@@ -0,0 +1,196 @@
+document.addEventListener('DOMContentLoaded', function() {
+  // Load Mermaid from CDN
+  const script = document.createElement('script');
+  script.src = 'https://cdn.jsdelivr.net/npm/[email protected]/dist/mermaid.min.js';
+  script.onload = function() {
+    // Initialize Mermaid when the script loads
+    mermaid.initialize({ 
+      startOnLoad: true,
+      theme: 'default',
+      securityLevel: 'loose',
+      flowchart: {
+        useMaxWidth: false,
+        htmlLabels: true
+      },
+      sequence: {
+        useMaxWidth: false
+      },
+      gantt: {
+        useMaxWidth: false
+      }
+    });
+
+    // Add zoom functionality to Mermaid diagrams
+    mermaid.init().then(() => {
+      document.querySelectorAll('.mermaid').forEach(function(diagram) {
+        // Make diagrams clickable for zoom
+        diagram.style.cursor = 'zoom-in';
+        diagram.style.maxWidth = '100%';
+        diagram.style.height = 'auto';
+        
+        // Add click handler for zoom
+        diagram.addEventListener('click', function() {
+          // Create zoom overlay
+          const overlay = document.createElement('div');
+          overlay.className = 'mermaid-zoom-overlay';
+          overlay.style.cssText = `
+            position: fixed;
+            top: 0;
+            left: 0;
+            width: 100%;
+            height: 100%;
+            background: rgba(0, 0, 0, 0.8);
+            display: flex;
+            justify-content: center;
+            align-items: center;
+            z-index: 9999;
+            cursor: grab;
+            overflow: hidden;
+          `;
+          
+          // Create container for panning
+          const container = document.createElement('div');
+          container.style.cssText = `
+            position: relative;
+            cursor: grab;
+            user-select: none;
+            transform-origin: center center;
+          `;
+          
+          // Clone the diagram for the overlay
+          const clonedDiagram = diagram.cloneNode(true);
+          clonedDiagram.style.cssText = `
+            max-width: none;
+            max-height: none;
+            background: white;
+            padding: 20px;
+            border-radius: 8px;
+            box-shadow: 0 4px 20px rgba(0, 0, 0, 0.3);
+            cursor: grab;
+            user-select: none;
+            transform-origin: center center;
+          `;
+          
+          container.appendChild(clonedDiagram);
+          overlay.appendChild(container);
+          document.body.appendChild(overlay);
+          
+          // Zoom and pan functionality
+          let scale = 1;
+          let translateX = 0;
+          let translateY = 0;
+          let isDragging = false;
+          let lastX = 0;
+          let lastY = 0;
+          
+          function updateTransform() {
+            container.style.transform = `translate(${translateX}px, ${translateY}px) scale(${scale})`;
+          }
+          
+          // Wheel zoom
+          overlay.addEventListener('wheel', function(e) {
+            e.preventDefault();
+            const delta = e.deltaY > 0 ? 0.9 : 1.1;
+            const newScale = Math.max(0.5, Math.min(5, scale * delta));
+            
+            if (newScale !== scale) {
+              const rect = overlay.getBoundingClientRect();
+              const centerX = rect.width / 2;
+              const centerY = rect.height / 2;
+              const mouseX = e.clientX - rect.left;
+              const mouseY = e.clientY - rect.top;
+              
+              const offsetX = mouseX - centerX;
+              const offsetY = mouseY - centerY;
+              
+              translateX = translateX - offsetX * (newScale / scale - 1);
+              translateY = translateY - offsetY * (newScale / scale - 1);
+              scale = newScale;
+              
+              updateTransform();
+            }
+          });
+          
+          // Mouse drag
+          container.addEventListener('mousedown', function(e) {
+            if (e.button === 0) { // Left mouse button
+              isDragging = true;
+              lastX = e.clientX;
+              lastY = e.clientY;
+              container.style.cursor = 'grabbing';
+              overlay.style.cursor = 'grabbing';
+              e.preventDefault();
+            }
+          });
+          
+          overlay.addEventListener('mousemove', function(e) {
+            if (isDragging) {
+              const deltaX = e.clientX - lastX;
+              const deltaY = e.clientY - lastY;
+              translateX += deltaX;
+              translateY += deltaY;
+              lastX = e.clientX;
+              lastY = e.clientY;
+              updateTransform();
+            }
+          });
+          
+          overlay.addEventListener('mouseup', function() {
+            isDragging = false;
+            container.style.cursor = 'grab';
+            overlay.style.cursor = 'grab';
+          });
+          
+          // Double-click to reset zoom
+          container.addEventListener('dblclick', function(e) {
+            e.stopPropagation();
+            scale = 1;
+            translateX = 0;
+            translateY = 0;
+            updateTransform();
+          });
+          
+          // Close on background click (but not on diagram)
+          overlay.addEventListener('click', function(e) {
+            if (e.target === overlay) {
+              document.body.removeChild(overlay);
+            }
+          });
+          
+          // Close on escape key
+          const escapeHandler = function(e) {
+            if (e.key === 'Escape') {
+              document.body.removeChild(overlay);
+              document.removeEventListener('keydown', escapeHandler);
+            }
+          };
+          document.addEventListener('keydown', escapeHandler);
+          
+          // Add instructions
+          const instructions = document.createElement('div');
+          instructions.style.cssText = `
+            position: absolute;
+            top: 20px;
+            left: 20px;
+            background: rgba(0, 0, 0, 0.7);
+            color: white;
+            padding: 10px 15px;
+            border-radius: 5px;
+            font-size: 14px;
+            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+            z-index: 10000;
+            pointer-events: none;
+          `;
+          instructions.innerHTML = `
+            <div>🔍 Scroll to zoom</div>
+            <div>🖱️ Drag to pan</div>
+            <div>📱 Double-click to reset</div>
+            <div>⌨️ ESC to close</div>
+          `;
+          overlay.appendChild(instructions);
+        });
+      });
+    });
+  };
+  document.head.appendChild(script);
+});

antora/supplemental-ui/js/mermaid-init.js

@@ -1,5 +1,6 @@
 <script id="site-script" src="{{uiRootPath}}/js/site.js" data-ui-root-path="{{{uiRootPath}}}"></script>
 <script src="{{uiRootPath}}/js/zoom.js"></script>
+<script src="{{uiRootPath}}/js/mermaid-init.js"></script>
 {{#if env.SITE_SEARCH_PROVIDER}}
 {{> search-scripts}}
 {{/if}}

antora/supplemental-ui/partials/footer-scripts.hbs

@@ -1,2 +1,3 @@
     <link rel="stylesheet" href="/css/site.min.css">
-    <link rel="stylesheet" href="{{{uiRootPath}}}/css/vendor/tabs.css">
+    <link rel="stylesheet" href="{{{uiRootPath}}}/css/vendor/tabs.css">
+    <link rel="stylesheet" href="{{{uiRootPath}}}/css/mermaid.css">