Project

state_machines-mermaid

0.0
No release in over 3 years
state_machines-mermaidstate-machines/state_machines-mermaidHomepageDocumentationSource CodeBug Tracker
Mermaid diagrams for state machines. Adds Mermaid diagram generation to state machines using the diagram gem
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
 Popularity
Downloads
225
Stars
6
Forks
0
Watchers
0
 Releases
Current version
0.1.0
Total releases
1
First release
1980-01-02
Latest release
1980-01-02
 Development
Primary Language
Ruby
Licenses
MIT
Average date of last 50 commits
2025-10-20
Reverse Dependencies
0

 Dependencies

Development

bundler
>= 0
minitest
>= 5.6.0
minitest-reporters
>= 0
rake
>= 0

Runtime

mermaid
>= 0
state_machines
>= 0.100.4
state_machines-diagram
>= 0.1.0
 Project Readme

StateMachines::Mermaid

CI Gem Version Supported Ruby

Mermaid diagram renderer for state_machines. Generate Mermaid state diagrams from your state machines.

Installation

Add this line to your application's Gemfile:

gem 'state_machines-mermaid'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install state_machines-mermaid

Usage

Basic Usage

require 'state_machines-mermaid'

class Order
  state_machine :status, initial: :pending do
    event :process do
      transition pending: :processing
    end
    
    event :ship do
      transition processing: :shipped
    end
    
    event :deliver do
      transition shipped: :delivered
    end
    
    event :cancel do
      transition [:pending, :processing] => :cancelled
    end
    
    state :delivered, :cancelled do
      def final?
        true
      end
    end
  end
end

# Generate Mermaid diagram
puts Order.state_machine(:status).draw

This generates:

stateDiagram-v2
  pending : pending
  processing : processing
  shipped : shipped
  delivered : delivered
  cancelled : cancelled
  pending --> processing : process
  processing --> shipped : ship
  shipped --> delivered : deliver
  pending --> cancelled : cancel
  processing --> cancelled : cancel
Loading

With Conditions

class Character
  state_machine :status, initial: :idle do
    event :attack do
      transition idle: :combat, if: :has_weapon?
    end
    
    event :rest do
      transition combat: :idle, unless: :in_danger?
    end
  end
end

# Generates transitions with conditions
puts Character.state_machine(:status).draw

Output includes conditions:

stateDiagram-v2
  idle : idle
  combat : combat
  idle --> combat : attack [if has_weapon?]
  combat --> idle : rest [unless in_danger?]
Loading

Show Callbacks

# Include callback information in the diagram
Character.state_machine(:status).draw(show_callbacks: true)

Output to File

File.open('state_diagram.mmd', 'w') do |file|
  Order.state_machine(:status).draw(io: file)
end

Integration with Mermaid Tools

The generated output is compatible with:

  • Mermaid Live Editor
  • GitHub Markdown (renders Mermaid diagrams natively)
  • Various documentation tools (GitLab, Notion, etc.)
  • Mermaid CLI for generating PNG/SVG files

Example: Complex State Machine

class Dragon
  state_machine :mood, initial: :sleeping do
    state :sleeping, :hunting, :hoarding, :rampaging
    
    event :wake_up do
      transition sleeping: :hunting, if: :hungry?
      transition sleeping: :hoarding, if: :treasure_nearby?
    end
    
    event :find_treasure do
      transition hunting: :hoarding
      transition hoarding: same  # Keep hoarding
    end
    
    event :enrage do
      transition any - :rampaging => :rampaging
    end
  end
end

puts Dragon.state_machine(:mood).draw

Features

  • Generates valid Mermaid state diagram syntax
  • Supports initial and final states
  • Shows transition conditions (if/unless)
  • Handles self-transitions (loopbacks)
  • Sanitizes state names for Mermaid compatibility
  • Optional callback visualization
  • Compatible with all state_machines features

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/state-machines/state_machines-mermaid.

License

The gem is available as open source under the terms of the MIT License.