Fix Mermaid Diagram Display Issues

If you're having trouble with Mermaid diagrams not displaying properly in the documentation, follow these troubleshooting steps:

Option 1: Use the Basic Diagrams Page

Visit the Basic Diagrams page for simplified, guaranteed-to-render versions of all critical diagrams.

Option 2: Add Custom JavaScript

If diagrams aren't rendering at all, your browser might need explicit initialization. Add this script to your browser console:

mermaid.initialize({
  startOnLoad: true,
  theme: 'default',
  securityLevel: 'loose',
  flowchart: {
    useMaxWidth: false,
    htmlLabels: true,
    curve: 'basis',
  },
});

// Force reinitialize all diagrams
setTimeout(function () {
  document.querySelectorAll('.mermaid').forEach(function (el) {
    if (el.innerHTML.trim()) {
      try {
        mermaid.init(undefined, el);
      } catch (e) {
        console.log('Error initializing mermaid diagram:', e);
      }
    }
  });
}, 1000);

Option 3: View Raw Diagram Source

You can always view the original diagram code in these files:

• /documentation/reference/architecture/visual-documentation.md

Simplified Diagram Syntax

For future diagrams, use these simplified patterns that are guaranteed to work:

graph TD
    A[Start] --> B{Decision?}
    B -->|Yes| C[Process 1]
    B -->|No| D[Process 2]
    C --> E[End]
    D --> E

This basic diagram shows a decision flow:

graph TD
    A[Start] --> B{Decision?}
    B -->|Yes| C[Process 1]
    B -->|No| D[Process 2]
    C --> E[End]
    D --> E