Mermaid Diagram Compatibility Guidelines

When creating or updating Mermaid diagrams for the documentation site, keep in mind the following compatibility guidelines to ensure they render correctly.

Common Issues

The MkDocs Material integration with Mermaid (version 11.6.0) may have different syntax requirements than the latest version of Mermaid. Here are the most common issues:

1. HTML in Nodes: HTML tags inside nodes may not render correctly:

# DON'T DO THIS ❌
flowchart TD
    A["<a href='link.md'>Link Text</a>"]

1. Complex Syntax: Some newer Mermaid features may not be supported:

# MAY NOT WORK ⚠️
timeline
    title Timeline of Events
    section 2023
      Launch: Project initiated
      Alpha: First alpha release

1. Special Characters: Some special characters might cause rendering issues:

   # BE CAREFUL WITH ⚠️
   flowchart TD
       A["Node with & < > characters"]

Best Practices

Follow these best practices for creating compatible Mermaid diagrams:

1. Keep It Simple: Use basic flowchart syntax whenever possible:

# DO THIS ✅
flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Process]
    B -->|No| D[End]

1. Use Comments for Links: Instead of HTML links, use comments and provide links below:

# DO THIS ✅
flowchart TD
    A[Start] --> B[See documentation]

See detailed documentation here

1. Test Locally: Always preview your diagrams locally before pushing changes.

2. Use the Live Editor: Check your diagrams in the Mermaid Live Editor and specify version 11.6.0 for compatibility testing.

Fixing Common Errors

If you encounter errors:

1. Syntax Error in Text: This usually means there's an unescaped character or unsupported syntax:

2. Check for special characters

3. Simplify your diagram

4. Make sure your diagram type is supported

5. Rendering Issues: If the diagram parses but looks wrong:

6. Check for proper node connections

7. Make sure your subgraphs are properly defined

8. Reduce complexity of the diagram

9. Missing Elements: If some elements don't appear:

10. Check for unsupported features
11. Make sure you're not using newer syntax features

Example of Fixing a Diagram

Original (Problematic):

flowchart TD
    A["<a href='docs.md'>Documentation</a>"] --> B["Process with & special chars"]
    click C "https://example.com"
    C --> D

Fixed Version:

flowchart TD
    A["Documentation"] --> B["Process with special chars"]
    C[External resource] --> D

See Documentation for more details. External resource provides additional context.

By following these guidelines, you'll ensure that your Mermaid diagrams render consistently in the documentation site.