Compatibility

Purpose

This page focuses specifically on Mermaid.js syntax compatibility - what works, what differs, and how to migrate. For a broader comparison with other diagram tools (PlantUML, Graphviz), see Tool Comparison.

Overview

Sirena maintains syntax compatibility with Mermaid.js while providing a pure Ruby implementation optimized for server-side rendering. This page documents the compatibility matrix, feature parity, and migration considerations specifically between Sirena and Mermaid.js.

Feature Comparison Matrix

Feature Mermaid.js Sirena Notes

Feature	Mermaid.js	Sirena	Notes
Diagram Types	20+	19	All major types supported
Rendering	Browser-based	Pure Ruby	Sirena is faster for server use
Themes	CSS-based	YAML-based	Easier customization in Sirena
Batch Mode	Manual scripting	Built-in	`sirena batch` command
Error Messages	Generic	Detailed	Better debugging in Sirena
Dependencies	Node + Puppeteer	Ruby only	Simpler deployment
File Size	~2MB (mermaid.min.js)	Ruby gem	Smaller footprint
Startup Time	~2s (browser launch)	<100ms	Much faster
Memory Usage	~200MB (Chrome)	~50MB	Lower resource usage
Interactive Features	Supported	Not supported	Static SVG only

Diagram Types

20+

19

All major types supported

Rendering

Browser-based

Pure Ruby

Sirena is faster for server use

Themes

CSS-based

YAML-based

Easier customization in Sirena

Batch Mode

Manual scripting

Built-in

sirena batch command

Error Messages

Generic

Detailed

Better debugging in Sirena

Dependencies

Node + Puppeteer

Ruby only

Simpler deployment

File Size

~2MB (mermaid.min.js)

Ruby gem

Smaller footprint

Startup Time

~2s (browser launch)

<100ms

Much faster

Memory Usage

~200MB (Chrome)

~50MB

Lower resource usage

Interactive Features

Supported

Not supported

Static SVG only

Diagram Type Support

Fully Compatible (100% Syntax Parity)

These diagram types have complete syntax compatibility with Mermaid.js:

Flowchart (graph, flowchart) - All node shapes, edge types, and subgraphs
Sequence Diagram (sequenceDiagram) - All participants, messages, and control structures
Class Diagram (classDiagram) - Classes, relationships, and annotations
State Diagram (stateDiagram-v2) - States, transitions, and nested states
ER Diagram (erDiagram) - Entities, attributes, and relationships
User Journey (journey) - Tasks, scores, and sections
Git Graph (gitGraph) - Commits, branches, merges, and tags
Pie Chart (pie) - Data and labels

Feature Complete

These types are fully implemented with minor differences:

Gantt Chart (gantt) - All features except click events
Quadrant Chart (quadrantChart) - All features
Requirement Diagram (requirementDiagram) - All features
C4 Diagram (all 5 types) - Context, Container, Component, Dynamic, Deployment
Mindmap (mindmap) - All node types and levels
Timeline (timeline) - All period types
Sankey (sankey-beta) - All flow types
XY Chart (xychart-beta) - All chart types
Block Diagram (block-beta) - All block types
Architecture (architecture-beta) - All component types
Kanban (kanban) - All column types

Additional Sirena Types

Radar Chart (radar) - Not in standard Mermaid.js
Treemap (treemap) - Not in standard Mermaid.js
Packet Diagram (packet) - Network packet visualization
Info Diagram (info) - Information display
Error Diagram (error) - Error state visualization

Not Supported

ZenUML - No specification available in Mermaid.js. Use sequenceDiagram instead.

Syntax Compatibility

Identical Syntax

The following syntax is 100% identical between Mermaid.js and Sirena:

Diagram type declarations
Node definitions
Edge/relationship definitions
Labels and text
Subgraphs and grouping
Comments (%%)
Title and accessibility attributes

Minor Differences

Styling

Mermaid.js:

graph TD
    A[Node]
    style A fill:#f9f,stroke:#333,stroke-width:4px

Sirena: Uses YAML themes instead of inline styles. Apply themes globally:

sirena render diagram.mmd --theme dark

Click Events

Mermaid.js: Supports click events and callbacks

graph TD
    A[Node]
    click A callback "Tooltip"

Sirena: Not supported (static SVG output)

Custom CSS Classes

Mermaid.js: Supports CSS class assignment

graph TD
    A[Node]
    class A myClass

Sirena: Use theme system for styling

Performance Comparison

Benchmarks for rendering 100 diagrams:

Metric	Mermaid.js	Sirena	Improvement
Total Time	~240s	~15s	16x faster
Memory Peak	~1.2GB	~150MB	8x less
Startup	~2s per diagram	~50ms per diagram	40x faster
Dependencies	Node, Puppeteer, Chrome	Ruby only	Simpler

Metric

Mermaid.js

Sirena

Improvement

Total Time

~240s

~15s

16x faster

Memory Peak

~1.2GB

~150MB

8x less

Startup

~2s per diagram

~50ms per diagram

40x faster

Dependencies

Node, Puppeteer, Chrome

Ruby only

Simpler

Migration Benefits

Why Migrate to Sirena?

Simpler Deployment

No Node.js required
No headless browser (Puppeteer/Chrome)
Single Ruby gem installation
Smaller Docker images

Better Performance

16x faster batch processing
8x lower memory usage
Faster CI/CD builds
Better for serverless

Native Ruby Integration

Rails helpers and views
Jekyll static sites
Rake task automation
Ruby gem ecosystem

Enhanced Tooling

Built-in batch processor
Better error messages
YAML-based themes
Command-line tools

Not Migrating? When to Use Each

Use Mermaid.js When:

You need interactive diagrams in browser
You need click events and callbacks
You have complex custom styling
You’re already using Node.js stack
You need real-time client-side rendering

Use Sirena When:

Server-side rendering is required
Building Ruby applications (Rails, Jekyll)
Batch processing many diagrams
CI/CD diagram generation
Simpler deployment is priority
Lower resource usage is important

Migration Path

See link:{% link _guides/migration-from-mermaid.adoc %}[Migration Guide] for:

Step-by-step migration instructions
Syntax conversion examples
Tool comparison
Performance optimization
Troubleshooting tips

Compatibility Testing

Sirena includes comprehensive compatibility testing:

# Run Mermaid.js compatibility tests
rake mermaid:validate

# Compare output with Mermaid.js
sirena render diagram.mmd -o sirena-output.svg
# Compare with mermaid-cli output

Future Compatibility

Sirena aims to maintain syntax parity with Mermaid.js. New Mermaid.js features will be evaluated for inclusion based on:

Server-side rendering applicability
Ruby ecosystem fit
Performance impact
Community demand

Getting Help

Issues: Report compatibility issues
Migration: link:{% link _guides/migration-from-mermaid.adoc %}[Migration Guide]
Examples: Example Diagrams

Sirena vs Mermaid.js Compatibility