Mermaid Support

Diagrammix3 supports importing and exporting diagrams using Mermaid syntax, a popular text-based diagramming language.

What is Mermaid?

Mermaid is a JavaScript-based diagramming tool that uses a markdown-like syntax to define diagrams. It's commonly used in documentation, wikis, and README files.

Example Mermaid syntax:

flowchart LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[End]

Importing Mermaid Diagrams

Note: Mermaid import and export are a PRO feature.

Insert Mermaid (with preview & validation)

The fastest way to bring Mermaid onto your canvas is the Insert Mermaid panel, which previews and validates the diagram before anything is placed.

1. Go to Edit → Insert Mermaid
2. Paste or type your Mermaid syntax into the editor
3. As you type, Diagrammix validates the syntax live and shows:
   • whether the diagram is valid
   • the detected diagram type
   • the node and connector counts
   
   Errors are flagged inline, so you can fix them before they ever touch your canvas.
4. Click Apply to place the diagram, or Cancel to dismiss

Pasting Mermaid from the clipboard runs through the same validation, so malformed syntax never produces a broken diagram.

Note: Mermaid is imported by pasting or typing into the Insert Mermaid panel — there is no separate "import file" command. To bring in a .mmd file, open it in any text editor and paste its contents.

Supported Diagram Types

Diagrammix recognizes a wide range of Mermaid diagram types, including:

Other Mermaid types (timeline, user journey, quadrant, XY chart, Sankey, Git graph, and more) are recognized and imported, but render as a generic node-and-connector graph rather than a specialized layout. The Insert Mermaid panel tells you the detected type before you apply.

State Diagram Syntax

State diagrams model the states an object can be in and transitions between states.

Basic State Diagram:

stateDiagram-v2
    [*] --> Active
    Active --> Inactive : deactivate
    Inactive --> Active : activate
    Active --> [*] : terminate

States and Transitions:

• [*] represents start and end states
• --> creates a transition arrow
• : label adds transition labels
• Nested states use indentation

Composite States:

stateDiagram-v2
    state Processing {
        [*] --> Validating
        Validating --> Executing
        Executing --> [*]
    }

Result: A state machine diagram with proper state shapes and labeled transitions.

Import Examples

Flowchart

Mermaid Input:

flowchart TD
    A[Hard edge] -->|Link text| B(Round edge)
    B --> C{Decision}
    C -->|One| D[Result one]
    C -->|Two| E[Result two]

Result: A top-down flowchart with rectangle, rounded rectangle, and diamond shapes connected with labeled arrows.

Sequence Diagram

Mermaid Input:

sequenceDiagram
    participant A as Alice
    participant B as Bob
    A->>B: Hello Bob!
    B-->>A: Hi Alice!

Result: A sequence diagram with two participants and message arrows.

Class Diagram

Mermaid Input:

classDiagram
    Animal <|-- Duck
    Animal <|-- Fish
    Animal : +int age
    Animal : +String gender
    Animal: +isMammal()

Result: A UML class diagram with inheritance relationships.

Exporting to Mermaid

Copy Mermaid

Diagrammix exports to Mermaid through the clipboard — there is no separate "export to file" command.

1. Select the shapes you want to export, or leave nothing selected to export the whole canvas
2. Go to Edit → Copy Mermaid
3. Paste the Mermaid syntax wherever you need it (then save it as a .mmd file if you like)

The export adapts to what's in scope: a mind map is copied as mindmap syntax and a UML class or sequence page as classDiagram / sequenceDiagram; anything else is exported as a flowchart.

Keep Editing in Mermaid (Round-Trip)

Imported Mermaid diagrams keep their source, so you can keep working in Mermaid notation instead of editing shapes one by one.

1. Select an imported Mermaid diagram
2. Click the </> (Edit Mermaid Source) button on the diagram
3. The Edit Mermaid Source panel opens with the original Mermaid text pre-filled
4. Edit the text and re-render to update the diagram in place

If your edits would change the diagram's structure (for example, removing nodes that other elements depend on), the panel lists those incompatibilities up front so you can decide before committing.

Editing as Native Objects

You can also edit an imported diagram directly as native Diagrammix objects:

• Move and resize shapes freely
• Change styles using the Inspector (colors, fonts, line styles)
• Add new elements using Diagrammix tools
• Modify connections by dragging endpoints
• Apply auto-layout to reorganize the diagram

Tip: Decide up front how you want to maintain a diagram. Use the </> source editor to keep it Mermaid-driven, or edit shapes directly for a one-off visual polish. Heavy manual edits can diverge from what re-rendering the source would produce.

Limitations

• Complex styling: Mermaid styling directives may not fully translate
• Subgraphs: Converted to grouped shapes
• Advanced features: Some Mermaid-specific features (like click handlers) are ignored
• Round-trip: Exporting a diagram you've heavily edited by hand may not reproduce identical Mermaid syntax — for round-trips, prefer the </> source editor

Tips

1. Clean up after import: Use auto-layout to organize imported diagrams
2. Check relationships: Verify that relationship types imported correctly
3. Style consistently: Apply Diagrammix styles for a polished look
4. Keep the source: Save your original Mermaid files for version control