Liquid Diagrams

Liquid Diagrams is a liquid plugins for rendering svg diagrams, it is inspired by asciidoctor-diagram. Currently support: Blockdiag, Bitfield, Erd, GraphViz, Mermaid, Nomnoml, Netlistsvg, PlantUML, Svgbob, Syntrax, Vega, Vegalite, Wavedrom.

• Installation
• Usage
  • Supported diagrams
  • Register diagrams
  • Use diagrams tag
  • Parse Configurations
• Prerequisites
• Configurations
  • Blockdiag
  • Bitfield
  • Erd
  • Graphviz
  • Mermaid
  • Netlistsvg
  • Nomnoml
  • PlantUML
  • State Machine Cat
  • Svgbob
  • Syntrax
  • Vega
  • Vegalite
  • Wavedrom
• Contributing
• License
• Code of Conduct

Installation

Add this line to your application's Gemfile:

gem 'liquid-diagrams'

And then execute:

bundle install

Or install it yourself as:

gem install liquid-diagrams

Usage

# Require `liquid_diagrams` or `liquid-diagrams`

require 'liquid_diagrams'

Supported diagrams

# All supported diagrams
LiquidDiagrams.diagrams
#=> [:actdiag, :blockdiag, :graphviz, :mermaid, ...]

Register diagrams

Diagrams must be registered before use, no diagrams is registered by default.

# Registered diagrams
LiquidDiagrams.registered_diagrams
# => {}

# Register one by one
LiquidDiagrams.register_diagram :graphviz

# Register in batch
LiquidDiagrams.register_diagrams :blockdiag, :mermaid

# Registered diagrams
LiquidDiagrams.registered_diagrams
# => {:graphviz => LiquidDiagrams::Blocks::GraphvizBlock, ...}

You can register all diagrams with:

LiquidDiagrams.register_diagrams(LiquidDiagrams.diagrams)

Use diagrams tag

Now you can use diagrams tag in liquid template:

content = <<~CONTENT
  {% blockdiag %}
    blockdiag {
      A -> B -> C -> D;
      A -> E -> F -> G;
    }
  {% endblockdiag %}
CONTENT

template = Liquid::Template.parse(content)
template.render
# => "<svg ...>...</svg>"

Parse Configurations

Configurations can be set for each diagrams when parse content:

content = <<~CONTENT
  {% blockdiag %}
    blockdiag {
      A -> B -> C -> D;
      A -> E -> F -> G;
    }
  {% endblockdiag %}
CONTENT

options = {
  blockdiag: {
    'scale' => 3
  }
  # options for other diagrams
}

template = Liquid::Template.parse(content, liquid_diagrams: options)
template.render
# => "<svg ...>...</svg>"

Prerequisites

You still need to install some dependencies, please refer to Prerequisites.

Configurations

Warning: All default configuration are provided by upstream, so it maybe different from here.

Blockdiag

Config	Type	Default	Description
antialias	boolean	unspecified	Pass diagram image to anti-alias filter
font	string	unspecified	use FONT to draw diagram
fontmap	string	unspecified	use FONTMAP file to draw diagram
size	int x int	unspecified	Size of diagram (ex. 320x240)

Bitfield

Config	Type	Default	Description
fontfamily	string	"sans-serif"	font family
fontweight	string	"normal"	font weight
fontsize	number	14	font size
lanes	number	2	rectangle lanes
vspace	number	80	vertical space
hspace	number	640	horizontal space
bits	number	32	overall bitwidth

Erd

Config	Type	Default	Description
config	string	unspecified	Configuration file
edge	string	unspecified	Select one type of edge
dot-entity	boolean	unspecified	Use dot tables instead of HTML tables

Available values:

• edge: compound, noedge, ortho, poly, spline

Graphviz

Config	Type	Default	Description
layout	string	dot	Set layout engine
graph_attributes	see below	unspecified	Set default graph attributes
node_attributes	see below	unspecified	Set default node attributes
edge_attributes	see below	unspecified	Set default edge attributes

NOTICE: attributes can be:

• String: eg. color=red
• Array: eg. ['color=blue', 'fontsize=14] or [['color', 'blue'], ['fontsize', '14']]
• Hash: eg. { color: 'green', fontsize: '14' }

Mermaid

Config	Type	Default	Description
width	int	800	Width of the page
height	int	600	Height of the page
backgroundColor	string	white	Background color
theme	string	default	Theme of the chart

Netlistsvg

Currently no configurations

Nomnoml

Currently no configurations

PlantUML

Currently no configurations

State Machine Cat

Config	Type	Default	Description
input-type	string	smcat	Input type
engine	string	dot	Layout engine to use
direction	string	top-down	Direction of the diagram

Available values:

• input-type: smcat, scxml, json
• egine: dot, circo, fdp, neato, osage, twopi
• direction: top-down, bottom-top, left-right, right-left

Svgbob

Config	Type	Default	Description
font-family	string	arial	Font
font-size	int	12	Font size
scale	int	1	Scale the entire svg
stroke-width	int	2	stroke width for all lines

Syntrax

Config	Type	Default	Description
scale	int	1	Scale image
style	string	unspecified	Style config file
transparent	boolean	unspecified	Transparent background

Vega

Config	Type	Default	Description
scale	int	1	Scale image

Vegalite

Config	Type	Default	Description
scale	int	1	Scale image

Wavedrom

Currently no configurations

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/zhustec/liquid-diagrams. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

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

Code of Conduct

Everyone interacting in the liquid-diagrams project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.