fix: improve Mermaid integration with better error handling and debugging

- Refactor to use enhanceApp approach for better VitePress compatibility
- Remove conflicting markdown-it-mermaid package
- Add comprehensive logging for debugging
- Improve error handling and processing state tracking
- Use proper router integration for route changes
- Add DOM ready state checking

This should resolve the issue where Mermaid diagrams appear as text
instead of being rendered as visual diagrams.

Author: Thavarshan

docs/.vitepress/theme/index.ts

@@ -1,82 +1,97 @@
-import { h } from 'vue'
 import DefaultTheme from 'vitepress/theme'
 import type { Theme } from 'vitepress'
-import { onMounted, watch, nextTick } from 'vue'
-import { useRoute } from 'vitepress'
 import './custom.css'
 
 export default {
   extends: DefaultTheme,
-  Layout: () => {
-    return h(DefaultTheme.Layout, null, {
-      // Custom layout slots if needed
-    })
-  },
-  enhanceApp() {
-    // Register global components if needed
-    // app.component('MyGlobalComponent', MyComponent)
-  },
-  setup() {
-    const route = useRoute()
+  enhanceApp({ router }) {
+    if (typeof window !== 'undefined') {
+      // Initialize Mermaid when the app starts
+      const initMermaid = async () => {
+        try {
+          console.log('Initializing Mermaid...')
+          const { default: mermaid } = await import('mermaid')
+          
+          mermaid.initialize({
+            startOnLoad: false,
+            theme: 'default',
+            themeVariables: {
+              primaryColor: '#3b82f6',
+              primaryTextColor: '#1f2937',
+              primaryBorderColor: '#e5e7eb',
+              lineColor: '#6b7280',
+              secondaryColor: '#f3f4f6',
+              tertiaryColor: '#ffffff',
+            },
+          })
+          
+          console.log('Mermaid initialized successfully')
 
-    const initializeMermaid = async () => {
-      // Only run on client side
-      if (typeof window === 'undefined') return
+          // Function to render mermaid diagrams
+          const renderMermaidDiagrams = async () => {
+            const mermaidElements = document.querySelectorAll('pre code.language-mermaid')
+            console.log(`Found ${mermaidElements.length} mermaid diagrams to render`)
+            
+            for (let i = 0; i < mermaidElements.length; i++) {
+              const element = mermaidElements[i] as HTMLElement
+              
+              // Skip if already processed
+              if (element.getAttribute('data-mermaid-processed')) {
+                console.log(`Skipping already processed diagram ${i}`)
+                continue
+              }
+              
+              const graphDefinition = element.textContent || ''
+              const graphId = `mermaid-diagram-${Date.now()}-${i}`
+              
+              console.log(`Processing mermaid diagram ${i}:`, graphDefinition.substring(0, 50) + '...')
 
-      const { default: mermaid } = await import('mermaid')
-      mermaid.initialize({
-        startOnLoad: false,
-        theme: 'default',
-        themeVariables: {
-          primaryColor: '#3b82f6',
-          primaryTextColor: '#1f2937',
-          primaryBorderColor: '#e5e7eb',
-          lineColor: '#6b7280',
-          secondaryColor: '#f3f4f6',
-          tertiaryColor: '#ffffff',
-        },
-      })
+              // Mark as being processed
+              element.setAttribute('data-mermaid-processed', 'processing')
 
-      // Find all mermaid code blocks and render them
-      const mermaidElements = document.querySelectorAll(
-        'pre code.language-mermaid'
-      )
-      mermaidElements.forEach((element, index) => {
-        const graphDefinition = element.textContent || ''
-        const graphId = `mermaid-${Date.now()}-${index}`
+              // Create container for the diagram
+              const container = document.createElement('div')
+              container.className = 'mermaid-diagram'
+              container.id = graphId
 
-        // Create a div to hold the rendered diagram
-        const mermaidDiv = document.createElement('div')
-        mermaidDiv.id = graphId
-        mermaidDiv.className = 'mermaid-diagram'
+              try {
+                // Render the mermaid diagram
+                const { svg } = await mermaid.render(graphId, graphDefinition)
+                container.innerHTML = svg
+                
+                // Replace the code block with the rendered diagram
+                const preElement = element.parentElement
+                if (preElement && preElement.parentElement) {
+                  preElement.parentElement.replaceChild(container, preElement)
+                  console.log(`Successfully rendered mermaid diagram ${i}`)
+                }
+              } catch (error) {
+                console.error(`Mermaid rendering failed for diagram ${i}:`, error)
+                // Keep the original code block on error
+                element.setAttribute('data-mermaid-processed', 'error')
+              }
+            }
+          }
 
-        // Replace the code block with the diagram
-        element.parentElement?.parentElement?.replaceChild(
-          mermaidDiv,
-          element.parentElement
-        )
+          // Render diagrams on initial load
+          renderMermaidDiagrams()
 
-        // Render the diagram
-        mermaid
-          .render(graphId, graphDefinition)
-          .then(({ svg }) => {
-            mermaidDiv.innerHTML = svg
-          })
-          .catch(error => {
-            console.error('Mermaid rendering error:', error)
-            mermaidDiv.innerHTML = `<pre><code>${graphDefinition}</code></pre>`
-          })
-      })
-    }
+          // Re-render on route changes
+          router.onAfterRouteChanged = () => {
+            setTimeout(renderMermaidDiagrams, 100)
+          }
 
-    onMounted(() => {
-      initializeMermaid()
-    })
+        } catch (error) {
+          console.error('Failed to initialize Mermaid:', error)
+        }
+      }
 
-    watch(
-      () => route.path,
-      () => nextTick(() => initializeMermaid()),
-      { immediate: true }
-    )
+      // Initialize after DOM is ready
+      if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', initMermaid)
+      } else {
+        initMermaid()
+      }
+    }
   },
 } satisfies Theme

package-lock.json

@@ -28,7 +28,6 @@
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "lucide-vue-next": "^0.542.0",
-    "markdown-it-mermaid": "^0.2.5",
     "mermaid": "^11.10.1",
     "radix-vue": "^1.9.17",
     "reka-ui": "^2.5.0",