Table of Contents

• Sirena vs Mermaid.js Compatibility
  • Purpose
  • Overview
  • Feature Comparison Matrix
  • Diagram Type Support
    • Not Supported
  • Syntax Compatibility
    • Shared Syntax
    • Minor Differences
  • Performance Comparison
  • Migration Benefits
    • Why Migrate to Sirena?
  • Not Migrating? When to Use Each
    • Use Mermaid.js When:
    • Use Sirena When:
  • Migration Path
  • Compatibility Testing
  • Future Compatibility
  • Getting Help
  • Related Documentation

Sirena vs Mermaid.js 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 reads Mermaid.js syntax in a pure Ruby implementation. This page documents measured compatibility and known differences between Sirena and Mermaid.js.

Feature Comparison Matrix

Feature	Mermaid.js	Sirena	Notes
Diagram Types	20+	24	24 types registered; compatibility varies by type, see scoreboard/corpus.json
Rendering	Browser-based	Pure Ruby	No browser or Node.js dependency
Themes	CSS-based	YAML-based	Sirena themes are YAML files or a Hash
Batch Mode	Manual scripting	Built-in	sirena batch command
Dependencies	Node + Puppeteer	Ruby only	Simpler deployment
File Size	~3.4 MB (mermaid.min.js in mermaid-cli 11.12.0)	Ruby gem	Not benchmarked
Startup Time	Measured in the linked dated Sirena report	Measured in the linked dated Sirena report	One Apple M2 run; see Performance Comparison below
Memory Usage	Not benchmarked	Not benchmarked	The recorded Sirena run did not measure memory
Interactive Features	Supported	Not supported	Static SVG only

Diagram Type Support

Pass rates below are measured per type against the valid-verdict corpus cases in scoreboard/corpus.json (bundle exec ruby scripts/corpus_sweep.rb then scripts/corpus_verdicts.rb). None of the 24 registered types has complete parity with Mermaid.js; "All features"-style claims for any individual type are not supported by this measurement and have been removed rather than asserted without evidence.

Generated from scoreboard/corpus.json. Counts cover only corpus cases that mmdc itself accepts (oracle verdict valid); extraction artifacts and cases mmdc rejects are excluded from the denominator.

Type	Syntax	Passing	Rate
Architecture	architecture-beta	19/19	100.0%
Block	block-beta	6/6	100.0%
C4	C4 (all 5 subtypes)	11/11	100.0%
Class Diagram	classDiagram	305/305	100.0%
ER Diagram	erDiagram	15/15	100.0%
Error Diagram	error	3/3	100.0%
Flowchart	graph, flowchart	218/218	100.0%
Gantt Chart	gantt	22/22	100.0%
Git Graph	gitGraph	128/128	100.0%
Info Diagram	info	11/11	100.0%
Kanban	kanban	39/39	100.0%
Mindmap	mindmap	45/45	100.0%
Packet Diagram	packet	4/4	100.0%
Pie Chart	pie	40/40	100.0%
Quadrant Chart	quadrantChart	9/9	100.0%
Radar Chart	radar	14/14	100.0%
Requirement Diagram	requirementDiagram	24/24	100.0%
Sankey	sankey-beta	0/0	n/a
Sequence Diagram	sequenceDiagram	107/107	100.0%
State Diagram	stateDiagram-v2	52/52	100.0%
Timeline	timeline	16/16	100.0%
Treemap	treemap	9/9	100.0%
User Journey	journey	27/27	100.0%
XY Chart	xychart-beta	1/1	100.0%

Regenerate with bundle exec rake docs:compatibility; spec/sirena/docs_compatibility_spec.rb fails when this table and scoreboard/corpus.json disagree.

Not Supported

• ZenUML - Not implemented. Mermaid publishes a syntax reference at https://mermaid.js.org/syntax/zenuml; use sequenceDiagram instead.

Syntax Compatibility

Shared Syntax

The following syntax elements exist in both Mermaid.js and Sirena; exact parity has not been verified element-by-element and is not claimed:

• 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: Inline style lines are accepted by the parser but have no effect on the output (measured: the node keeps the theme fill and stroke). Apply a theme globally instead:

sirena render diagram.mmd --theme dark

Click Events

Mermaid.js: Supports click events and callbacks

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

Sirena: click lines are accepted and ignored; no link or callback is emitted (static SVG output)

Custom CSS Classes

Mermaid.js: Supports CSS class assignment

graph TD
    A[Node]
    class A myClass

Sirena: class and classDef lines are accepted and ignored; use the theme system for styling

Performance Comparison

The benchmark:compare and benchmark:quick rake tasks run against Sirena.render. One dated Apple M2 comparison with mermaid-cli, its method, and reproduction commands is published in the Performance Benchmark report. That report did not measure memory, and one machine’s result is not a general performance guarantee. Sirena’s lack of a browser or Node.js dependency remains a structural difference, not itself a timing measurement.

Migration Benefits

Why Migrate to Sirena?

Simpler Deployment

• No Node.js required

• No headless browser (Puppeteer/Chrome)

• Single Ruby gem installation

No Browser Dependency

• No headless browser or Node.js runtime to run

• The recorded benchmark is scoped to one machine and contains no memory measurement (see Performance Comparison above)

Ruby Ecosystem

• Rake task automation ships today (tasks/*.rake)

• Rails helpers/views and Jekyll-specific integration are not built; using Sirena from a Rails or Jekyll app today means calling Sirena.render yourself, the same as from any other Ruby code

Enhanced Tooling

• Built-in batch processor

• 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 that can call Sirena.render directly

• Batch processing many diagrams

• CI/CD diagram generation

• Simpler deployment is priority

Migration Path

A migration guide is planned.

Compatibility Testing

Compatibility can be checked with:

# 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 for syntax parity with Mermaid.js; the table above is the measured state. 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

• Examples: Example Diagrams

Related Documentation

• Tool Comparison - Compare Sirena with Mermaid.js, PlantUML, and Graphviz

• Diagram Types Reference - Syntax for all diagram types