🎨 Interactive Mermaid Editor

A powerful visual editor for Mermaid diagrams with persistent positioning, real-time editing, and bidirectional synchronization between visual elements and code.

✨ Features

🎯 Dual Rendering Modes

• Mermaid Renderer: Standard Mermaid.js rendering with automatic layout
• D3 Renderer: Interactive D3.js rendering with persistent positioning

🖱️ Visual Editing

• Drag & Drop: Move nodes with mouse - positions stay permanently
• Click to Edit: Select any node or edge to edit properties
• Real-time Updates: Changes appear instantly in the diagram
• Shape Support: Rectangles, circles, diamonds with live transformation

🎨 Styling & Customization

• Node Properties: Text, colors, shapes, sizes
• Edge Properties: Labels, colors, line styles, widths
• Color Picker: Full color customization with live preview
• Multiple Shapes: Rectangle [text], Circle (text), Diamond {text}

🔄 Bidirectional Sync

• Visual → Code: Edit visually, Mermaid code updates automatically
• Code → Visual: Paste Mermaid code, renders with all features
• Syntax Preservation: Maintains proper Mermaid syntax compatibility

💾 Project Management

• Export Projects: Save complete layouts with positioning data
• Import Projects: Restore exact layouts from saved files
• Position Persistence: Node positions survive page refreshes
• Mermaid Export: Standard .mmd file export for compatibility

🎪 Advanced Features

• Subgraph Support: Group nodes for better organization
• Dark Mode: Toggle between light and dark themes
• PNG Export: High-resolution image export
• Layout Memory: Automatic position saving via localStorage

🚀 Quick Start

Method 1: Local Web Server (Recommended)

1. Clone the repository

   git clone git@bitbucket.org:zlalani/mermaid-edit.git
   cd mermaid-edit
   

2. Start local server (choose one):

   PHP Built-in Server:

   php -S localhost:8000
   

   Python HTTP Server:

   # Python 3
   python -m http.server 8000
   # Python 2
   python -m SimpleHTTPServer 8000
   

   Node.js HTTP Server:

   npx http-server -p 8000
   

3. Open in browser

   http://localhost:8000
   

Method 2: Web Server Deployment

1. Upload files to your web server
2. Configure PHP (if using PHP features)
3. Set permissions (755 for directories, 644 for files)
4. Access via domain/IP

📖 Usage Guide

Getting Started

1. Create a diagram by typing Mermaid syntax in the left panel
2. Choose renderer:
   • Click "Render Diagram" for standard Mermaid
   • Click "Render with D3" for interactive editing
3. Start editing - click nodes/edges to customize

Interactive Editing Workflow

Basic Editing

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

1. Click "Render with D3"
2. Drag nodes to desired positions
3. Click nodes to edit text, colors, shapes
4. Click edges to edit labels, styles, colors
5. Positions save automatically

Project Management

• Export Project: Saves everything (code + positions + styling)
• Import Project: Restores exact layout from saved file
• Export .mmd: Standard Mermaid file for other tools
• Export PNG: High-resolution image

Supported Mermaid Syntax

Node Types

A[Rectangle]          # Rectangle shape
B(Rounded)            # Circle/rounded shape  
C{Diamond}            # Diamond shape
D((Circle))           # Perfect circle

Connection Types

A --> B               # Arrow
A --- B               # Line
A -.-> B              # Dotted arrow
A ==> B               # Thick arrow
A -->|Label| B        # Labeled connection

Styling

flowchart TD
    A[Node] --> B[Another]
    
    style A fill:#f96,color:#fff
    style B fill:#bbf,color:#000
    linkStyle 0 stroke:#f66,stroke-width:3px

🔧 Configuration

Basic Configuration (config.php)

<?php
define('SITE_TITLE', 'Interactive Mermaid Editor');
define('DEBUG_MODE', false);
?>

Customization Options

• Canvas Size: Modify width and height in D3 renderer
• Color Defaults: Update default colors in CSS variables
• Theme Settings: Customize light/dark mode colors

🌐 Browser Compatibility

Browser	Version	Status
Chrome	88+	✅ Full Support
Firefox	85+	✅ Full Support
Safari	14+	✅ Full Support
Edge	88+	✅ Full Support

Requirements:

• Modern browser with ES6+ support
• JavaScript enabled
• LocalStorage support (for position persistence)

📁 Project Structure

mermaid-edit/
├── index.php              # Main application
├── config.php             # Configuration
├── css/
│   └── style.css          # Styles (legacy)
├── js/                    # JavaScript (legacy)
├── OLD/                   # Previous versions
├── README.md              # This file
└── .git/                  # Git repository

🔄 Export/Import Format

Project Export (.json)

{
  "version": "1.0",
  "exportedAt": "2024-01-15T10:30:00.000Z",
  "mermaidCode": "flowchart TD\n    A[Start] --> B[End]",
  "d3Data": {
    "nodes": [
      {
        "id": "A",
        "text": "Start",
        "shape": "rect",
        "position": {"x": 240, "y": 100, "fx": 240, "fy": 100},
        "style": {"fill": "#ffc406", "color": "#000000"}
      }
    ],
    "edges": [
      {
        "source": "A",
        "target": "B", 
        "label": "",
        "type": "-->",
        "style": {"stroke": "#000", "strokeWidth": 2}
      }
    ]
  },
  "renderSettings": {
    "width": 800,
    "height": 600,
    "renderer": "D3"
  },
  "metadata": {
    "title": "My Diagram",
    "description": "Interactive Mermaid project"
  }
}

🚨 Troubleshooting

Common Issues

Q: Positions don't save

• A: Use "Render with D3" for persistent positioning
• A: Check browser localStorage is enabled

Q: Import doesn't work

• A: Ensure JSON file format is valid
• A: Check browser console for error messages

Q: Shapes don't match Mermaid syntax

• A: Verify correct syntax: [rect], (round), {diamond}
• A: Check console for parsing errors

Q: Performance issues

• A: Large diagrams may be slow in D3 mode
• A: Use standard Mermaid mode for complex diagrams

🤝 Contributing

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Mermaid.js - Original diagram rendering
• D3.js - Interactive visualizations
• Contributors - All developers who helped improve this tool

📞 Support

• Issues: Create GitHub Issue
• Documentation: This README and inline code comments
• Community: Share your diagrams and get help

---

Made with ❤️ for better diagram editing

Interactive Mermaid Editor - Where visual meets code