Table of Contents

• Features
• What’s in This Section
• Feature Documentation Format
• Core Features
  • Rendering & Output
  • Theming & Styling
  • Parsing & Validation
  • Productivity Features
• Built-in Themes
• Integration Features
  • Build Tool Integration
• Performance Features
• Unique Advantages
  • vs. Mermaid.js
• Extensibility
• Related Documentation

Features

Detailed documentation of Sirena’s unique features and capabilities.

What’s in This Section

In-depth coverage of:

• Theme System - YAML-based theming with built-in themes

• Batch Processing - Processing multiple diagrams efficiently

• CLI Tools - Command-line interface capabilities

• Parslet Parsing - Grammar-based parsing architecture

• SVG Generation - Self-contained SVG output

• Error Handling - Parse errors report line and column

• Layout Engine - Built-in fallback grid layout; flowcharts can opt in to elkrb with layout_engine: :elk

• Text Measurement - Per-glyph advances for the default font stack

• Color Palettes - Theme color system

• Typography - Font and text styling

• Shape Styles - Node and edge styling

Feature Documentation Format

Each feature page includes:

• Overview - What the feature does

• Use cases - When to use this feature

• How it works - Technical explanation

• Configuration - How to configure

• Examples - Practical demonstrations

• Best practices - Recommended usage

• Troubleshooting - Common issues

Core Features

This section names the features; the individual per-feature pages it used to link to (svg-generation.adoc, layout-engine.adoc, etc.) are not written yet, so these are described inline rather than linked.

Rendering & Output

• SVG Generation - Scalable vector output

• Layout Engine - Built-in fallback grid layout; flowcharts can opt in to elkrb with layout_engine: :elk

• Text Measurement - Per-glyph advance table for the default font stack (Arial, Helvetica, sans-serif); not measured from the font a viewer actually uses

Theming & Styling

• Theme System - YAML-based themes

• Color Palettes - Theme colors

• Typography - Font system

• Shape Styles - Node and edge styling

Parsing & Validation

• Parslet Parsing - Grammar-based parser

• Error Handling - Parse errors report line and column

Productivity Features

• Batch Processing - Multiple diagrams at once, processed sequentially

• CLI Tools - Command-line interface

Built-in Themes

Sirena includes four built-in themes:

• Default - Classic Mermaid.js-compatible styling

• Dark - Dark background with high contrast

• Light - Minimalist light theme

• High Contrast - Higher-contrast colors

See Compatibility Comparison for how Sirena’s themes map to Mermaid.js’s.

Integration Features

Sirena is a plain Ruby gem: Sirena.render can be called from any Ruby application, Rake task, or CI script. There is no Rails engine, Jekyll plugin, or Metanorma-specific integration code in the gem today — its SVG output is self-contained (no external CSS) so it embeds cleanly wherever an app already handles SVG, including Metanorma documents.

Build Tool Integration

• Rake Tasks - tasks/*.rake covers example generation and corpus checks during development

• CI/CD - Runs anywhere a Ruby CI job can (GitHub Actions and others)

Performance Features

• Batch Processing - Renders a directory of files sequentially (sirena batch); not parallelized

No caching layer or plugin system exists yet.

Unique Advantages

vs. Mermaid.js

• No Node.js - Pure Ruby, no JavaScript runtime

• No Browser - No Puppeteer/headless Chrome

• Native Ruby - First-class Ruby integration

A dated Apple M2 comparison run and the commands used to reproduce it are published in the Performance Benchmark report. It did not measure memory and does not establish a machine-independent speed multiplier.

Extensibility

Sirena is extended through Sirena::Notation.register(plugin), which adds a whole notation (see ARCHITECTURE.md, "Registry Pattern (Notation)"), and sirena render --require to load such a file. Built-in diagram types are rows of Sirena::Notation::Mermaid::TYPES. Sirena::DiagramRegistry is a read-only, deprecated facade and has no register method.

• Custom Themes - Create your own themes (name, Theme, or Hash)

Related Documentation

• Tutorials - Learn by doing

• Guides - In-depth topics

• References - API documentation