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 (~30% Feature Complete)

• ✅ Basic state definitions and transitions
• ✅ Start/end states
• ❌ Composite states
• ❌ Parallel states
• ❌ State actions and guards

Sequence Diagrams (~25% Feature Complete)

• ✅ Basic actor interactions
• ✅ Simple message flows
• ❌ Activation boxes
• ❌ Loops and alternatives
• ❌ Notes and comments

🚧 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

🚀 Quick Start

Installation

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

Basic Usage

package main

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

func main() {
    // Parse a Mermaid diagram
    input := `flowchart TD
        A[Start] --> B{Decision}
        B -->|Yes| C[Process]
        B -->|No| D[Alternative]
        C --> E[End]
        D --> E`

    mermaidParser := parser.NewMermaidParser()
    diagram, err := mermaidParser.Parse(input)
    if err != nil {
        log.Fatal(err)
    }

    // Render back to Mermaid syntax
    mermaidRenderer := renderer.NewMermaidRenderer()
    output, err := mermaidRenderer.Render(diagram)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(output)
}

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