sirena 0.1.0

data/docs/_pages/compatibility.adoc

@@ -0,0 +1,300 @@
+---
+layout: default
+title: Compatibility
+parent: Core Topics
+nav_order: 4
+---
+
+== 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 link:comparison/[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
+
+[cols="3,2,2,2"]
+|===
+|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 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:**
+[source,mermaid]
+----
+graph TD
+    A[Node]
+    style A fill:#f9f,stroke:#333,stroke-width:4px
+----
+
+**Sirena:**
+Uses YAML themes instead of inline styles. Apply themes globally:
+[source,bash]
+----
+sirena render diagram.mmd --theme dark
+----
+
+===== Click Events
+
+**Mermaid.js:** Supports click events and callbacks
+[source,mermaid]
+----
+graph TD
+    A[Node]
+    click A callback "Tooltip"
+----
+
+**Sirena:** Not supported (static SVG output)
+
+===== Custom CSS Classes
+
+**Mermaid.js:** Supports CSS class assignment
+[source,mermaid]
+----
+graph TD
+    A[Node]
+    class A myClass
+----
+
+**Sirena:** Use theme system for styling
+
+=== Performance Comparison
+
+Benchmarks for rendering 100 diagrams:
+
+[cols="2,2,2,2"]
+|===
+|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:
+
+[source,bash]
+----
+# 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**: https://github.com/claricle/sirena/issues[Report compatibility issues]
+* **Migration**: link:{% link _guides/migration-from-mermaid.adoc %}[Migration Guide]
+* **Examples**: https://github.com/claricle/sirena/tree/main/examples[Example Diagrams]
+
+=== Related Documentation
+
+* link:comparison/[Tool Comparison] - Compare Sirena with Mermaid.js, PlantUML, and Graphviz
+* link:{% link _guides/migration-from-mermaid.adoc %}[Migration from Mermaid.js] - Step-by-step migration guide
+* link:{% link _diagram_types/index.adoc %}[Diagram Types Reference] - Syntax for all diagram types
+* link:{% link _features/theme-system.adoc %}[Theme System] - YAML-based theming
+* link:{% link _guides/performance-optimization.adoc %}[Performance Optimization] - Optimization techniques

data/docs/_pages/index.adoc

@@ -0,0 +1,39 @@
+---
+layout: default
+title: Core Topics
+nav_order: 2
+has_children: true
+---
+
+== Core Topics
+
+Essential concepts and information you need to understand and use Sirena effectively.
+
+== What's in This Section
+
+This section covers fundamental topics including:
+
+* **Installation** - How to install and set up Sirena
+* **Architecture** - Understanding Sirena's design and components
+* **Theming System** - How themes work in Sirena
+* **Compatibility** - Mermaid.js syntax compatibility matrix
+* **Comparison** - Sirena vs Mermaid.js vs PlantUML vs Graphviz
+* **Configuration** - Configuring Sirena for your needs
+
+== Quick Navigation
+
+Browse the topics in the sidebar or use the search function to find specific information.
+
+== Getting Started
+
+If you're new to Sirena, we recommend starting with:
+
+. link:{% link _tutorials/getting-started.adoc %}[Getting Started Tutorial]
+. link:{% link _pages/architecture.adoc %}[Architecture Overview]
+. link:{% link _diagram_types/index.adoc %}[Diagram Types Reference]
+
+== Need Help?
+
+* See link:{% link _tutorials/index.adoc %}[Tutorials] for step-by-step guides
+* Check link:{% link _references/index.adoc %}[References] for API documentation
+* Visit our https://github.com/claricle/sirena/issues[GitHub Issues] for support

data/docs/_references/index.adoc

@@ -0,0 +1,103 @@
+---
+layout: default
+title: References
+nav_order: 7
+has_children: true
+---
+
+== References
+
+Complete API, CLI, and configuration references for quick lookup.
+
+== What's in This Section
+
+Comprehensive reference documentation:
+
+* **CLI Reference** - Complete command-line interface
+* **API Reference** - Programmatic API documentation
+* **Theme Reference** - Theme configuration schema
+* **Error Codes** - All error codes and meanings
+* **Configuration** - Configuration options
+* **Mermaid Compatibility** - Syntax compatibility matrix
+
+== Reference Format
+
+Each reference page provides:
+
+* **Quick lookup tables** - Find information fast
+* **Complete listings** - Exhaustive documentation
+* **Examples** - Usage demonstrations
+* **Notes** - Important details and caveats
+* **See also** - Related documentation
+
+== Command-Line Interface
+
+=== link:{% link _references/cli-reference.adoc %}[CLI Reference]
+
+Complete documentation of all `sirena` commands:
+
+* `sirena render` - Render a single diagram
+* `sirena batch` - Process multiple diagrams
+* `sirena types` - List supported diagram types
+* `sirena version` - Show version information
+
+== Programmatic API
+
+=== link:{% link _references/api-reference.adoc %}[API Reference]
+
+Ruby API documentation:
+
+* `Sirena.render()` - Main rendering method
+* `Sirena::Engine` - Core engine class
+* `Sirena::Theme` - Theme system
+* `Sirena::Parser` - Parser classes
+* `Sirena::Renderer` - Renderer classes
+
+== Configuration
+
+=== link:{% link _references/theme-reference.adoc %}[Theme Reference]
+
+Complete theme configuration schema:
+
+* Color palette configuration
+* Typography settings
+* Shape styles
+* Spacing configuration
+* Effect styles
+
+== Error Handling
+
+=== link:{% link _references/error-codes.adoc %}[Error Codes]
+
+All error codes with:
+
+* Error code number
+* Error message
+* Cause explanation
+* Resolution steps
+* Examples
+
+== Compatibility
+
+=== link:{% link _references/mermaid-compatibility.adoc %}[Mermaid Compatibility]
+
+Feature-by-feature comparison:
+
+* Supported syntax
+* Unsupported features
+* Behavioral differences
+* Migration notes
+
+== Quick Reference Cards
+
+Downloadable quick references:
+
+* link:{% link _references/cli-quick-reference.adoc %}[CLI Quick Reference]
+* link:{% link _references/api-quick-reference.adoc %}[API Quick Reference]
+* link:{% link _references/syntax-quick-reference.adoc %}[Syntax Quick Reference]
+
+== Related Documentation
+
+* link:{% link _tutorials/index.adoc %}[Tutorials] - Learn step-by-step
+* link:{% link _guides/index.adoc %}[Guides] - In-depth topics
+* link:{% link _diagram_types/index.adoc %}[Diagram Types] - Syntax for each type

data/docs/_tutorials/index.adoc

@@ -0,0 +1,57 @@
+---
+layout: default
+title: Tutorials
+nav_order: 3
+has_children: true
+---
+
+== Tutorials
+
+Step-by-step tutorials to help you accomplish specific tasks with Sirena.
+
+== What's in This Section
+
+Hands-on tutorials covering:
+
+* **Getting Started** - Installation and first diagram
+* **CLI Usage** - Command-line interface walkthrough
+* **Rails Integration** - Using Sirena in Rails applications
+* **Jekyll Integration** - Static site generation with Sirena
+* **Batch Processing** - Processing multiple diagrams at once
+* **Theme Customization** - Creating and applying custom themes
+
+== Tutorial Format
+
+Each tutorial includes:
+
+* **Prerequisites** - What you need before starting
+* **Step-by-step instructions** - Clear, actionable steps
+* **Code examples** - Copy-paste ready code
+* **Expected results** - What you should see
+* **Troubleshooting** - Common issues and solutions
+
+== Recommended Learning Path
+
+For beginners:
+
+. link:{% link _tutorials/getting-started.adoc %}[Getting Started]
+. link:{% link _tutorials/cli-usage.adoc %}[CLI Usage]
+. link:{% link _tutorials/creating-first-diagram.adoc %}[Creating Your First Diagram]
+
+For application integration:
+
+. link:{% link _tutorials/rails-integration.adoc %}[Rails Integration]
+. link:{% link _tutorials/jekyll-integration.adoc %}[Jekyll Integration]
+
+For advanced usage:
+
+. link:{% link _tutorials/batch-processing.adoc %}[Batch Processing]
+. link:{% link _tutorials/theme-customization.adoc %}[Theme Customization]
+
+== Next Steps
+
+After completing tutorials:
+
+* Explore link:{% link _guides/index.adoc %}[Guides] for in-depth topics
+* Reference link:{% link _diagram_types/index.adoc %}[Diagram Types] for syntax
+* Check link:{% link _references/index.adoc %}[API Reference] for programmatic use

data/docs/index.adoc

@@ -0,0 +1,166 @@
+---
+layout: default
+title: Home
+nav_order: 1
+description: "Sirena: Pure Ruby Mermaid diagram renderer with 19 diagram types"
+permalink: /
+---
+
+== Sirena Documentation
+
+Welcome to Sirena, a pure Ruby Mermaid diagram rendering library that converts Mermaid syntax into beautiful SVG diagrams. Built for server-side rendering, Sirena provides native integration with Ruby applications without requiring Node.js or browser dependencies.
+
+== Why Sirena?
+
+=== Pure Ruby Implementation
+* No Node.js dependencies
+* No Puppeteer/Chrome requirements
+* Simpler deployment in Ruby environments
+* Native integration with Rails, Jekyll, and Ruby applications
+
+=== Better Performance
+* Faster startup (no browser launch)
+* Lower memory footprint
+* Better for batch processing
+* Suitable for serverless environments
+
+=== Comprehensive Diagram Support
+* 19 diagram types fully implemented
+* Mermaid.js syntax compatibility
+* Advanced theming system
+* Professional-quality SVG output
+
+== Quick Start
+
+[source,ruby]
+----
+# Installation
+gem install sirena
+
+# Basic usage
+require 'sirena'
+
+svg = Sirena.render(<<~MERMAID)
+  graph TD
+    Start --> End
+MERMAID
+
+puts svg
+----
+
+See link:{% link _tutorials/getting-started.adoc %}[Getting Started Tutorial] for complete installation and usage instructions.
+
+== Documentation Structure
+
+=== link:{% link _pages/index.adoc %}[Core Topics]
+Essential concepts and architecture you need to understand Sirena.
+
+=== link:{% link _tutorials/index.adoc %}[Tutorials]
+Step-by-step guides to help you get started and accomplish specific tasks.
+
+=== link:{% link _guides/index.adoc %}[Guides]
+In-depth guides for advanced features and best practices.
+
+=== link:{% link _diagram_types/index.adoc %}[Diagram Types]
+Complete reference for all 19 diagram types with syntax and examples.
+
+=== link:{% link _features/index.adoc %}[Features]
+Detailed documentation of Sirena's unique features and capabilities.
+
+=== link:{% link _references/index.adoc %}[References]
+Complete API and CLI references for quick lookup.
+
+== Supported Diagram Types
+
+Sirena supports 19 diagram types compatible with Mermaid.js syntax:
+
+[cols="1,3"]
+|===
+|Type |Use Case
+
+|link:{% link _diagram_types/flowchart.adoc %}[Flowchart]
+|Process flows and directed graphs
+
+|link:{% link _diagram_types/sequence-diagram.adoc %}[Sequence]
+|Message interactions over time
+
+|link:{% link _diagram_types/class-diagram.adoc %}[Class]
+|Object-oriented class structures
+
+|link:{% link _diagram_types/state-diagram.adoc %}[State]
+|State machines and transitions
+
+|link:{% link _diagram_types/er-diagram.adoc %}[ER Diagram]
+|Database entity relationships
+
+|link:{% link _diagram_types/user-journey.adoc %}[User Journey]
+|User experience mapping
+
+|link:{% link _diagram_types/git-graph.adoc %}[Git Graph]
+|Repository history visualization
+
+|link:{% link _diagram_types/pie-chart.adoc %}[Pie Chart]
+|Proportional data visualization
+
+|link:{% link _diagram_types/gantt-chart.adoc %}[Gantt Chart]
+|Project timeline planning
+
+|link:{% link _diagram_types/quadrant-chart.adoc %}[Quadrant]
+|Priority/complexity matrices
+
+|link:{% link _diagram_types/requirement-diagram.adoc %}[Requirement]
+|Requirements traceability
+
+|link:{% link _diagram_types/c4-diagram.adoc %}[C4]
+|Software architecture (Context, Container, Component, Code)
+
+|link:{% link _diagram_types/mindmap.adoc %}[Mindmap]
+|Hierarchical idea organization
+
+|link:{% link _diagram_types/timeline.adoc %}[Timeline]
+|Historical event visualization
+
+|link:{% link _diagram_types/sankey-diagram.adoc %}[Sankey]
+|Flow quantity visualization
+
+|link:{% link _diagram_types/xy-chart.adoc %}[XY Chart]
+|Data point plotting
+
+|link:{% link _diagram_types/block-diagram.adoc %}[Block]
+|Component relationships
+
+|link:{% link _diagram_types/architecture-diagram.adoc %}[Architecture]
+|System architecture views
+
+|link:{% link _diagram_types/kanban-diagram.adoc %}[Kanban]
+|Workflow board visualization
+|===
+
+See the complete link:{% link _diagram_types/index.adoc %}[Diagram Types Reference] for detailed syntax and examples.
+
+== Key Features
+
+* **Theme System**: YAML-based theming with 4 built-in themes (default, dark, light, high-contrast)
+* **Batch Processing**: Built-in batch renderer for documentation sets
+* **Rails Integration**: Native Ruby integration with Rails helpers
+* **Jekyll Support**: Static site generation compatibility
+* **Parslet Parsing**: Robust grammar-based parsing with clear error messages
+* **SVG Output**: Professional-quality scalable vector graphics
+
+== Compatibility & Comparison
+
+Sirena maintains syntax compatibility with Mermaid.js while providing a pure Ruby implementation optimized for server-side rendering.
+
+* link:{% link _pages/compatibility.adoc %}[Mermaid.js Compatibility] - Detailed syntax compatibility matrix
+* link:{% link _pages/comparison.adoc %}[Tool Comparison] - Compare Sirena with Mermaid.js, PlantUML, and Graphviz
+
+== Getting Help
+
+* **Report Issues**: https://github.com/claricle/sirena/issues[GitHub Issues]
+* **Source Code**: https://github.com/claricle/sirena[GitHub Repository]
+* **RubyGems**: https://rubygems.org/gems/sirena[Sirena Gem]
+* **Migration Guide**: link:{% link _guides/migration-from-mermaid.adoc %}[Migrating from Mermaid.js]
+
+== License
+
+Sirena is open source under the MIT License.

data/docs/lychee.toml

@@ -0,0 +1,54 @@
+# Cache results between runs
+cache = true
+
+# Maximum number of concurrent link checks
+max_concurrency = 16
+
+# Accept status codes
+accept = [200, 204, 301, 302, 307, 308, 403, 429]
+
+# Exclude patterns
+exclude = [
+    # Skip local file URLs that won't exist in production
+    '^file://',
+    # Skip mailto links
+    '^mailto:',
+    # Skip anchors without base URL
+    '^#',
+]
+
+# Include patterns
+include = [
+    # Check all HTTP/HTTPS links
+    '^https?://',
+]
+
+# Timeout for each request (in seconds)
+timeout = 30
+
+# Number of retries
+max_retries = 3
+
+# User agent
+user_agent = "lychee/link-checker"
+
+# Exclude certain file types from link checking
+exclude_file = []
+
+# Skip checking links in certain HTML elements
+exclude_mail = true
+
+# Check for broken fragments (anchors)
+check_anchors = true
+
+# Verify SSL certificates
+require_https = false
+
+# Follow redirects
+follow_redirects = true
+
+# Maximum redirect depth
+max_redirects = 10
+
+# Verbosity
+verbose = true