# Mermaid-Go

A high-performance Go implementation of Mermaid diagram parsing and rendering, providing near-complete compatibility with [Mermaid.js](https://mermaid.js.org/) 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 (<<interface>>, <<abstract>>, <<enumeration>>)
- ✅ 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

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

### Basic Usage

```go
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

```bash
# 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
```mermaid
flowchart TD
    A[Start] --> B[Process]
    B --> C{Decision}
    C -->|Yes| D[Success]
    C -->|No| E[Failure]
```

#### Advanced Features
```mermaid
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
```mermaid
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
```mermaid
classDiagram
    class Animal {
        +String name
        +int age
        +makeSound() void
        -validateAge(int age) boolean
    }
```

#### Advanced Class Features
```mermaid
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
```mermaid
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
```bash
go test ./...
```

### Test Specific Diagram Types
```bash
# Test flowcharts
go run test_flowchart_advanced.go

# Test class diagrams
go run test_class_advanced.go
```

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

## 🎨 Advanced Features

### Interactive Elements
```mermaid
flowchart TD
    A[Button] --> B[Action]

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

### Styling and Themes
```mermaid
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
```mermaid
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
```go
parser := parser.NewMermaidParser()
parser.SetStrictMode(true)  // Enable strict syntax validation
parser.SetDebugMode(true)   // Enable detailed error messages
```

### Renderer Options
```go
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
```mermaid
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
```mermaid
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](LICENSE) file for details.

## 🙏 Acknowledgments

- [Mermaid.js](https://mermaid.js.org/) 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](https://github.com/your-org/mermaid-go/issues)
- **Documentation**: [Wiki](https://github.com/your-org/mermaid-go/wiki)
- **Discussions**: [GitHub Discussions](https://github.com/your-org/mermaid-go/discussions)

---

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