mermaid-go

Mermaid-Go

A high-performance Go implementation of Mermaid diagram parsing and rendering, providing near-complete compatibility with Mermaid.js syntax.

🎯 Project Goals

Mermaid-Go aims to provide a native Go alternative to Mermaid.js with:

• High Performance: Fast parsing and rendering without JavaScript runtime overhead
• Native Integration: Easy embedding in Go applications and CLI tools
• Broad Compatibility: Support for the most commonly used Mermaid diagram types
• Extensibility: Clean architecture for adding new diagram types and features

📊 Current Support Status

✅ Fully Supported Diagram Types

Flowchart Diagrams (~85% Feature Complete)

• ✅ All standard node shapes (rectangle, circle, diamond, parallelogram, etc.)
• ✅ Edge types (solid, dotted, thick arrows)
• ✅ Subgraphs with titles and directions
• ✅ Interactive features (click events, links, callbacks)
• ✅ Styling (classDef, class assignments, individual node styles)
• ✅ Direction control (TD, TB, BT, RL, LR)
• ⚠️ Edge labels and animations (partial support)
• ❌ Markdown text formatting

Class Diagrams (~80% Feature Complete)

• ✅ Class definitions with members and methods
• ✅ Method parameters and return types
• ✅ Visibility modifiers (+, -, #, ~)
• ✅ Class relationships (inheritance, composition, aggregation, etc.)
• ✅ Annotations (<>, <>, <>)
• ✅ Comments (%% syntax)
• ✅ Notes (general and class-specific)
• ✅ Direction control
• ⚠️ Generic types (framework ready, parsing in progress)
• ❌ Click events and links

🔄 Partially Supported

State Diagrams (~75% Feature Complete)

• ✅ Basic state definitions and transitions
• ✅ Start/end states
• ✅ State actions (entry, exit, do)
• ✅ Transition guards and actions
• ✅ Notes and annotations
• ✅ Special states (choice, fork, join, history)
• ⚠️ Composite states (framework ready)
• ⚠️ Parallel states (framework ready)

Sequence Diagrams (~80% Feature Complete)

• ✅ Basic actor interactions
• ✅ Simple message flows
• ✅ Multiple arrow types (->, -->, ->>, -->>, -x, --x, -), --), <->)
• ✅ Activation boxes (activate/deactivate)
• ✅ Loops and alternatives (loop, alt, opt)
• ✅ Parallel sections (par)
• ✅ Notes and comments
• ✅ Participant boxes and grouping
• ⚠️ Complex nesting (framework ready)
• ❌ Auto-numbering and styling

🚧 Planned Support

• ER Diagrams: Entity-relationship diagrams
• Gantt Charts: Project timeline visualization
• User Journey: User experience flow mapping
• Requirement Diagrams: Requirements and relationships
• Timeline: Chronological event visualization

🌟 Key Features

• 🚀 High Performance: Fast parsing and rendering without JavaScript runtime overhead
• 🇨🇳 Full Unicode Support: Complete support for Chinese, Japanese, Korean and all Unicode characters
• 🔄 Bidirectional Conversion: Mermaid syntax ↔ Go structs (AST) ↔ Mermaid syntax
• 🖼️ Image Export: High-quality SVG export with Chinese character support
• 🏗️ Native Integration: Easy embedding in Go applications and CLI tools
• 📊 Broad Compatibility: Support for 24+ diagram types with intelligent auto-detection

🚀 Quick Start

Installation

go get github.com/your-org/mermaid-go

Enhanced Usage with Auto-Detection

package main

import (
    "fmt"
    "log"
    "mermaid-go/pkg/ast"
    "mermaid-go/pkg/detector"
    "mermaid-go/pkg/parser"
    "mermaid-go/pkg/renderer"
)

func main() {
    // Auto-detect and parse any Mermaid diagram type
    input := `sequenceDiagram
        participant U as User
        participant S as Server
        U -> S : request
        S --> U : response`

    // Create main parser with auto-detection
    mermaidParser := parser.NewMermaidParser()
    
    // Detect diagram type
    diagramType := mermaidParser.GetDiagramType(input)
    fmt.Printf("Detected diagram type: %s\n", diagramType)
    
    // Parse the diagram
    diagram, err := mermaidParser.Parse(input)
    if err != nil {
        log.Fatal(err)
    }

    // Render back to Mermaid syntax
    switch d := diagram.(type) {
    case *ast.SequenceDiagram:
        renderer := renderer.NewSequenceRenderer()
        output, _ := renderer.Render(d)
        fmt.Println(output)
    case *ast.StateDiagram:
        renderer := renderer.NewStateRenderer()
        output, _ := renderer.Render(d)
        fmt.Println(output)
    // ... handle other diagram types
    }
}

Enhanced Sequence Diagrams

// Parse a complex sequence diagram with loops, alternatives, and parallel sections
input := `
sequenceDiagram
    participant U as User
    participant W as WebApp
    participant S as Server
    participant D as Database
    
    U -> W : login request
    activate W
    
    loop Authentication
        W -> S : validate credentials
        S -> D : query user
        D --> S : user data
    end
    
    alt Valid credentials
        S --> W : success
        W --> U : login complete
    else Invalid credentials
        S --> W : failure
        W --> U : login failed
    end
    
    par User actions
        U -> W : browse content
    and Background tasks
        S -> D : cleanup sessions
    end
    
    deactivate W
    `
    
parser := parser.NewSequenceParser()
diagram, err := parser.Parse(input)
// ... rest of the code

Enhanced State Diagrams

// Parse a state diagram with guards, actions, and notes
input := `
stateDiagram-v2
    [*] --> Idle
    Idle --> Processing : start [hasData] / processData
    Processing --> Idle : complete [success] / cleanup
    Processing --> Error : fail [error] / logError
    
    note right of Processing : Main processing state
    note left of Error : Error handling
    `
    
parser := parser.NewStateParser()
diagram, err := parser.Parse(input)
// ... rest of the code

🎯 Recent Enhancements

🧠 Intelligent Diagram Type Detection

• Auto-Detection: Automatically detects 24+ diagram types from input text
• Priority-Based: More specific patterns detected first (e.g., stateDiagram-v2 before stateDiagram)
• Robust Parsing: Handles comments, directives, and front matter

🔧 Enhanced Lexical Analysis

• Rich Arrow Support: 20+ arrow types including bidirectional, dotted, crossed, and directional markers
• Special State Handling: Proper recognition of complex diagram declarations
• Mermaid.js Compatibility: Follows official mermaidjs lexical patterns

🏗️ Modular Architecture

• Detector Registry: Extensible system for adding new diagram types
• Parser Router: Centralized parsing with type-specific handlers
• Clean Separation: Lexical analysis, parsing, and rendering are fully decoupled

Chinese Character Support

mermaid-go fully supports Unicode characters including Chinese, Japanese, and Korean:

// Chinese pie chart
input := `pie showData
    title 2024年市场份额分析
    "阿里巴巴" : 35
    "腾讯" : 30
    "百度" : 20
    "字节跳动" : 15`

// Chinese sequence diagram  
input := `sequenceDiagram
    participant 用户 as 用户端
    participant 系统 as 后端系统
    用户 ->> 系统: 登录请求
    系统 -->> 用户: 登录响应`

Command Line Usage

# Parse and validate a Mermaid file
go run main.go parse diagram.mmd

# Convert between formats
go run main.go convert input.mmd output.mmd

📖 Supported Syntax

Flowchart Examples

Basic Flowchart

flowchart TD
    A[Start] --> B[Process]
    B --> C{Decision}
    C -->|Yes| D[Success]
    C -->|No| E[Failure]

Advanced Features

flowchart LR
    subgraph "User Actions"
        A([Login]) --> B{Authenticated?}
    end

    subgraph "System Process"
        C[Process Request] --> D[Generate Response]
    end

    B -->|Yes| C
    B -->|No| A

    %% Styling
    classDef userClass fill:#e1f5fe,stroke:#01579b,stroke-width:2px
    class A,B userClass

    %% Interactive elements
    click A "https://example.com/login" "_blank"
    click C callback

Complex Node Shapes

flowchart TB
    A([Start/End]) --> B[Rectangle]
    B --> C(Rounded)
    C --> D{Diamond}
    D --> E[/Parallelogram/]
    E --> F[\Alt Parallelogram\]
    F --> G>Flag]
    G --> H[[Subroutine]]
    H --> I((Circle))

Class Diagram Examples

Basic Class Definition

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound() void
        -validateAge(int age) boolean
    }

Advanced Class Features

classDiagram
    %% Interface definition
    class Shape {
        <<interface>>
        +area() double
        +perimeter() double
    }

    %% Abstract class
    class AbstractShape {
        <<abstract>>
        +String color
        +getColor() String
        +setColor(String color) void
        +area()* double
    }

    %% Relationships
    Shape <|-- AbstractShape
    AbstractShape <|-- Circle
    AbstractShape <|-- Rectangle

    %% Notes
    note "This is a shape hierarchy example"
    note for Shape "Defines the basic shape interface"

Method Parameters and Types

classDiagram
    class Calculator {
        +add(int a, int b) int
        +subtract(double x, double y) double
        +multiply(float[] numbers) float
        -validateInput(Object input) boolean
    }

🏗️ Architecture

mermaid-go/
├── pkg/
│   ├── ast/          # Abstract Syntax Tree definitions
│   │   ├── flowchart.go
│   │   ├── class.go
│   │   └── ...
│   ├── lexer/        # Tokenization
│   │   └── lexer.go
│   ├── parser/       # Syntax analysis
│   │   ├── mermaid.go
│   │   ├── flowchart.go
│   │   ├── class.go
│   │   └── ...
│   └── renderer/     # Output generation
│       ├── mermaid.go
│       ├── flowchart.go
│       └── class.go
├── cmd/             # CLI applications
├── examples/        # Usage examples
└── tests/          # Test diagrams

Key Components

• Lexer: Tokenizes Mermaid syntax into a stream of tokens
• Parser: Builds Abstract Syntax Trees (AST) from token streams
• AST: Represents diagram structure in memory
• Renderer: Converts AST back to Mermaid syntax or other formats

🧪 Testing

Run Basic Tests

go test ./...

Test Specific Diagram Types

# Test flowcharts
go run test_flowchart_advanced.go

# Test class diagrams
go run test_class_advanced.go

Validation Examples

# Test round-trip parsing
echo 'flowchart TD; A --> B' | go run main.go validate

🎨 Advanced Features

Interactive Elements

flowchart TD
    A[Button] --> B[Action]

    click A "https://example.com" "_blank"
    click B callback

Styling and Themes

flowchart LR
    A --> B --> C

    classDef default fill:#f9f9f9,stroke:#333,stroke-width:2px
    classDef highlight fill:#ff6b6b,stroke:#c92a2a,stroke-width:3px

    class B highlight

Subgraphs and Organization

flowchart TB
    subgraph Frontend ["Frontend Layer"]
        direction LR
        A[React App] --> B[API Client]
    end

    subgraph Backend ["Backend Services"]
        direction TB
        C[REST API] --> D[Database]
    end

    Frontend --> Backend

🔧 Configuration

Parser Options

parser := parser.NewMermaidParser()
parser.SetStrictMode(true)  // Enable strict syntax validation
parser.SetDebugMode(true)   // Enable detailed error messages

Renderer Options

renderer := renderer.NewMermaidRenderer()
renderer.SetIndentation("    ")  // Set custom indentation
renderer.SetCompactMode(false)   // Pretty-print output

🤝 Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/new-diagram-type
3. Make your changes and add tests
4. Run tests: go test ./...
5. Submit a pull request

Adding New Diagram Types

1. Define AST structures in pkg/ast/
2. Implement parser in pkg/parser/
3. Add renderer in pkg/renderer/
4. Write tests and examples
5. Update documentation

Current Development Priorities

1. Complete Generic Types support for Class Diagrams
2. Markdown Text Formatting for all diagram types
3. Edge Labels and Animations for Flowcharts
4. ER Diagram implementation
5. Gantt Chart support

📚 Examples and Tutorials

Real-World Use Cases

Software Architecture Documentation

flowchart TD
    subgraph "Client Tier"
        A[Web Browser] --> B[Mobile App]
    end

    subgraph "Application Tier"
        C[Load Balancer] --> D[API Gateway]
        D --> E[Microservice 1]
        D --> F[Microservice 2]
    end

    subgraph "Data Tier"
        G[(Primary DB)] --> H[(Replica DB)]
        I[Cache Layer]
    end

    A --> C
    B --> C
    E --> G
    F --> G
    E --> I
    F --> I

Class Hierarchy Documentation

classDiagram
    class Vehicle {
        <<abstract>>
        +String brand
        +int year
        +start() void
        +stop() void
        +getInfo()* String
    }

    class Car {
        +int doors
        +String fuelType
        +getInfo() String
        +openTrunk() void
    }

    class Motorcycle {
        +boolean hasSidecar
        +getInfo() String
        +popWheelie() void
    }

    Vehicle <|-- Car
    Vehicle <|-- Motorcycle

    note for Vehicle "Base class for all vehicles"

与 mermaid.js 的对应关系

该项目的设计严格遵循 mermaid.js 的内部架构：

mermaid.js	mermaid-go
flow.jison	pkg/lexer/lexer.go + pkg/parser/flowchart.go
flowDb.ts	pkg/parser/flowchart.go (FlowDB)
classDiagram.jison	pkg/parser/class.go
types.ts	pkg/ast/flowchart.go, pkg/ast/class.go
flowRenderer.ts	pkg/renderer/flowchart.go

项目作者

由 gytmtc 创建，基于 mermaid.js 的架构设计，现已扩展支持多种图表类型和高级特性。

📄 License

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

🙏 Acknowledgments

• Mermaid.js for the original specification and inspiration
• The Go community for excellent parsing libraries and patterns
• All contributors who help improve this project

📞 Support

• Issues: GitHub Issues
• Documentation: Wiki
• Discussions: GitHub Discussions

---

Current Version: 0.8.0 (Alpha) Mermaid.js Compatibility: ~82% of core features Status: Active Development