Project

sirena

0.0
The project is in a healthy, maintained state
sirenaclaricle/sirenaHomepageDocumentationSource CodeBug TrackerWiki
Sirena is a pure Ruby implementation of Mermaid diagram rendering. It parses Mermaid syntax and generates SVG output using Parslet grammars and ELK layout. Supports 24 diagram types: flowcharts, sequence, class, state, ER, C4, block, architecture, Gantt, timeline, Git graph, mindmap, Kanban, user journey, pie, quadrant, radar, XY charts, requirement, Sankey, packet, treemap, info, and error displays.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
 Popularity
Downloads
1,207
Stars
0
Forks
0
Watchers
0
 Releases
Current version
0.1.0
Total releases
1
First release
2025-12-26
Latest release
2025-12-26
 Issues
Open Issues
0
Closed Issues
1
Total Issues
1
Issue Closure Rate
100%
 Development
Primary Language
Ruby
Licenses
BSD-2-Clause
Average date of last 50 commits
2026-01-07
Reverse Dependencies
0

 Dependencies

Development

rake
>= 0
rspec
>= 0
rubocop
>= 0

Runtime

lutaml-model
~> 0.7
moxml
>= 0
plurimath-parslet
~> 3.0
thor
>= 0
 Project Readme

Sirena

RubyGems Version License Build

Purpose

Sirena is a pure Ruby interpreter of commonly-used diagram generation languages into SVG format.

Sirena currently supports the following diagram definition syntaxes:

  • Mermaid - the text-based diagramming language defined in mermaid-js

Sirena aims to provide high compatibility with the original tools while offering a pure Ruby implementation that can be easily integrated into Ruby-based workflows and tools.

Note
 The name "Sirena" is derived from "Siren", a mythological creature known for its enchanting songs that lure sailors, as its usage in multiple languages refer to mermaids.

Implementation notes

The library follows strict object-oriented principles with a model-driven architecture, using Lutaml::Model for all data structures and providing clean separation between parsing, transformation, layout, and rendering phases.

Features

Diagram language support

Mermaid defines a set of diagram type languages for composing different diagram types.

Sirena currently supports all diagram type languages defined in Mermaid.

Mermaid diagram types

Sirena supports all 24 Mermaid diagram types with complete parser, transform, and renderer implementations:

  • Flowchart - Directional graphs with various node shapes and edge types

  • Sequence diagram - Message flows between participants over time

  • Class diagram - UML class relationships and hierarchies

  • State diagram - State machine transitions and hierarchies

  • Entity-relationship diagram - Database schema relationships

  • User journey - User interaction flows with satisfaction levels

  • Gantt chart - Project timelines and task dependencies

  • Pie chart - Proportional data visualization

  • Quadrant chart - 2D data point categorization

  • Requirement diagram - Requirements and their relationships

  • Git graph - Git branching and commit history

  • Mindmap - Hierarchical mind mapping

  • Timeline - Event sequences over time

  • Sankey diagram - Flow quantities between nodes

  • XY chart - Line and bar charts with axes

  • Block diagram - Block-based architecture diagrams

  • Packet diagram - Network packet structure

  • C4 diagram - Software architecture contexts and containers

  • Architecture diagram - Service and component architecture

  • Kanban board - Workflow status tracking

  • Radar chart - Multi-dimensional data comparison

  • Treemap - Hierarchical data as nested rectangles

  • Error diagram - Error message display

  • Info diagram - Information display

See examples/README.adoc for working examples of all diagram types.

Core capabilities

  • Pure Ruby implementation - No JavaScript dependencies

  • Parslet-based parsing - Superior error messages and maintainability

  • SVG output - Standards-compliant SVG 1.2

  • Theme support - 4 built-in themes, custom theme support

  • Auto-detection - Automatic diagram type detection

  • Batch processing - Process multiple diagrams at once

  • CLI tool - Command-line interface for standalone usage

  • Programmatic API - Ruby library for custom workflows

  • Metanorma integration - Direct embedding in documentation

Installation

Via RubyGems

Add Sirena to your Gemfile:

gem 'sirena'

Then execute:

bundle install

Or install it directly:

gem install sirena

Requirements

Ruby 2.7 or higher.

Quick start

Command-line usage

Render a single Mermaid diagram to SVG:

sirena render diagram.mmd -o output.svg

Render all Mermaid files in a directory:

sirena batch input_dir/ -o output_dir/

List all supported diagram types:

sirena types

Programmatic usage

Use Sirena in your Ruby code:

require 'sirena'

# Render from a string
mermaid_code = <<~MERMAID
  graph TD
    A[Start] --> B[Process]
    B --> C[End]
MERMAID

svg = Sirena::Engine.render(mermaid_code)
File.write('output.svg', svg)

# Render from a file
svg = Sirena::Engine.render_file('diagram.mmd')
File.write('output.svg', svg)

# Specify diagram type explicitly
svg = Sirena::Engine.render(mermaid_code, type: :flowchart)

Examples

Browse examples/README.adoc for 37 working examples across all 24 diagram types, each with corresponding SVG output.

Documentation

Comprehensive documentation is available at the Sirena Documentation Site.

Quick links

Documentation Structure

The documentation uses a 6-collection architecture:

  1. Core Topics - Installation, architecture, compatibility, comparison, configuration

  2. Tutorials - Step-by-step learning paths

  3. Guides - Task-oriented how-to documentation

  4. Diagram Types - Complete reference for all 24 diagram types with examples

  5. Features - Detailed capability documentation

  6. References - API and CLI reference

See the documentation site for the complete guide.

Architecture

General

Sirena implements a pipeline architecture that transforms Mermaid source code through distinct processing stages, each with clear responsibilities and well-defined interfaces.

All parsers use Parslet, a powerful PEG (Parsing Expression Grammar) library that provides superior error messages, composability, and maintainability compared to traditional lexer-based approaches. The 3-layer Parslet architecture (Grammar → Transform → Parser) achieved ~80% code reduction during migration.

The implementation uses the ELK layout engine via the elkrb gem for professional-quality graph layout and positioning. Sirena is a pure Ruby implementation with no JavaScript dependencies, generating standards-compliant SVG 1.2 output suitable for direct integration with Metanorma documentation frameworks.

Sirena processing pipeline
Mermaid Syntax Input (String)
         │
         ▼
    ┌─────────┐
    │ Parser  │  Parslet Grammar → Transform → Parser
    └────┬────┘  (3-layer architecture)
         │
         ▼
   ┌───────────┐
   │ Diagram   │  Lutaml::Model AST
   │   Model   │  (Flowchart, Sequence, etc.)
   └─────┬─────┘
         │
         ▼
   ┌───────────┐
   │Transform  │  Diagram → Graph Conversion
   │  Layer    │
   └─────┬─────┘
         │
         ▼
   ┌───────────┐
   │  Layout   │  Position Computation
   │  Engine   │  (Node positions, edge routes)
   └─────┬─────┘
         │
         ▼
   ┌───────────┐
   │    SVG    │  Graph → SVG Conversion
   │ Renderer  │
   └─────┬─────┘
         │
         ▼
   ┌───────────┐
   │    SVG    │  Lutaml::Model Structure
   │  Builder  │
   └─────┬─────┘
         │
         ▼
  SVG XML Output (String)
Component relationships
Sirena (Root Module)
    │
    ├── Engine (Orchestrator)
    │     ├── coordinates overall flow
    │     ├── delegates to Parser
    │     ├── delegates to Transform
    │     └── delegates to Renderer
    │
    ├── Parser (Parslet-based Syntax Analysis)
    │     ├── Grammars (Parslet rules)
    │     ├── Transforms (tree conversion)
    │     └── produces Diagram Models
    │
    ├── Diagram (Domain Models)
    │     ├── Architecture
    │     ├── Block
    │     ├── C4
    │     ├── ClassDiagram
    │     ├── ErDiagram
    │     ├── Error
    │     ├── Flowchart
    │     ├── Gantt
    │     ├── GitGraph
    │     ├── Info
    │     ├── Kanban
    │     ├── Mindmap
    │     ├── Packet
    │     ├── Pie
    │     ├── Quadrant
    │     ├── Radar
    │     ├── Requirement
    │     ├── Sankey
    │     ├── Sequence
    │     ├── StateDiagram
    │     ├── Timeline
    │     ├── Treemap
    │     ├── UserJourney
    │     └── XyChart
    │
    ├── Transform (Model Conversion)
    │     └── diagram-specific converters
    │
    ├── Renderer (SVG Generation)
    │     └── diagram-specific renderers
    │
    ├── Svg (SVG Models)
    │     ├── Document, Element, Group
    │     ├── Path, Text, Rect
    │     └── Circle, Line, Polygon
    │
    └── DiagramRegistry (Type Registration)
          └── maps types to handlers

Parslet-based parser architecture

All 24 implemented diagram types use Parslet exclusively for parsing, following a consistent 3-layer pattern:

  1. Layer 1: Grammar (Parslet::Parser) - Defines syntax rules using Parslet DSL, parses text into intermediate tree structures

  2. Layer 2: Transform (Parslet::Transform) - Converts intermediate trees to typed Diagram models using pattern matching

  3. Layer 3: Parser - Orchestrates Grammar and Transform, provides public API

This architecture provides:

  • Superior error messages with detailed context and line numbers

  • Composability through shared grammar rules across diagram types

  • Maintainability via declarative, self-documenting syntax rules

  • Type safety through strongly-typed Lutaml::Model objects

  • Code reduction of ~80% compared to previous lexer-based approach

See ARCHITECTURE.md for detailed architecture documentation.

Test coverage

General

Sirena implements comprehensive test coverage against the official mermaid-js test suite to ensure compatibility and correctness. The test suite validates all diagram types and syntax variations against reference outputs generated using mermaid-cli.

Mermaid-js compatibility validation

Sirena’s test suite includes test cases that covers all diagram types to ensure comprehensive compatibility and correctness.

The test suite generates 302 SVG reference fixtures using mermaid-cli v11.12.0.

Copyright and license

Copyright Ribose.

This software is licensed under the Ribose BSD-3 clause license.