Jekyll Diagrams

Jekyll Diagrams is a jekyll plugins for creating diagrams, currently support for Blockdiag, Erd, GraphViz, Mermaid, Nomnoml, PlantUML, Svgbob, Syntrax, Vega, Vega-Lite and WaveDrom. More diagrams support will be added in future versions.

NOTICE: This plugin render SVG format image and directly embed into html file, so you don't need to worry about where to store the image. But, please feel free to tell me if you unlikely want other image format.

• Installation
• Configuration
• Usage
  • Blockdiag
  • Erd
  • Graphviz
  • Mermaid
  • Nomnoml
  • PlantUML
  • State Machine Cat
  • Svgbob
  • Syntrax
  • Vega
  • Wavedrom
• Contributing
• License

Installation

Add the following to your site's _config.yml:

plugins:
  - jekyll-diagrams

And the following to your site's Gemfile:

group :jekyll_plugins do
  gem 'jekyll-diagrams'
end

Finally run:

$ bundle install

Configuration

All configurations are under jekyll-diagrams, e.g:

jekyll-diagrams:
  graphviz:
    # configurations for graphviz
  blockdiag:
    # configurations for blockdiag
  syntrax:
    # configurations for syntrax
  # and so on

Usage

Blockdiag

Prerequisites

Install it.

$ pip3 install blockdiag seqdiag actiag nwdiag

Then you can use following tags:

• blockdiag
• seqdiag
• actdiag
• nwdiag
• rackdiag
• packetdiag

Examples

{% blockdiag %}
blockdiag {
   A -> B -> C -> D;
   A -> E -> F -> G;
}
{% endblockdiag %}

And seqdiag:

{% seqdiag %}
seqdiag {
  browser  -> webserver [label = "GET /index.html"];
  browser <-- webserver;
  browser  -> webserver [label = "POST /blog/comment"];
              webserver  -> database [label = "INSERT comment"];
              webserver <-- database;
  browser <-- webserver;
}
{% endseqdiag %}

Configurations

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

Erd

Prerequisites

• Install Graphviz
• Install Erd

$ sudo apt install graphviz cabal-install
$ cabal update && cabal install erd

Examples

{% erd %}
[Person]
*name
height
weight
`birth date`
+birth_place_id

[`Birth Place`]
*id
`birth city`
'birth state'
"birth country"

Person *--1 `Birth Place`
{% enderd %}

Configurations

Config	Default	Description
config	unspecified	Configuration file
edge	unspecified	Select one type of edge: compound, noedge, ortho, poly, spline
dot-entity	unspecified	When set, output will consist of regular dot tables instead of HTML tables. Formatting will be disabled

Graphviz

Prerequisites

Install it.

Examples

{% graphviz %}
digraph {
  node [shape=circle, style=filled];
  S [fillcolor=green];
  A [fillcolor=yellow];
  B [fillcolor=yellow];
  C [fillcolor=yellow];
  D [shape=doublecircle, fillcolor=green];
  S -> A [label=a];
  S -> B [label=b];
  A -> D [label=c];
  B -> D [label=d];
}
{% endgraphviz %}

Configurations

Config	Default	Description
default_layout	dot	Set default layout engine
graph_attributes	unspecified	Set default graph attribute
node_attributes	unspecified	Set default node attribute
edge_attributes	unspecified	Set default edge attribute

NOTICE: attributes can be String(when just one attribute), Array or Hash.

Mermaid

Prerequisites

Install mermaid.cli.

$ npm install -g mermaid.cli

Configurations

Config	Default	Description
theme	default	Theme of the chart, could be default, forest, dark or neutral
width	800	Width of the page
height	600	Height of the page
backgroundColor	white	Background color. Example: transparent, red, '#F0F0F0'

Nomnoml

Prerequisites

Install it.

$ npm install -g nomnoml

Examples

{% nomnoml %}
[Pirate|eyeCount: Int|raid();pillage()|
  [beard]--[parrot]
  [beard]-:>[foul mouth]
]

[<abstract>Marauder]<:--[Pirate]
[Pirate]- 0..7[mischief]
[jollyness]->[Pirate]
[jollyness]->[rum]
[jollyness]->[singing]
[Pirate]-> *[rum|tastiness: Int|swig()]
[Pirate]->[singing]
[singing]<->[rum]

[<start>st]->[<state>plunder]
[plunder]->[<choice>more loot]
[more loot]->[st]
[more loot] no ->[<end>e]

[<actor>Sailor] - [<usecase>shiver me;timbers]
{% endnomnoml %}

PlantUML

Prerequisites

Install java runtime.

$ sudo apt install default-jre

Examples

{% plantuml %}
@startuml
class Car

Driver - Car : drives >
Car *- Wheel : have 4 >
Car -- Person : < owns

@enduml
{% endplantuml %}

State Machine Cat

Prerequisites

Install it.

$ npm install -g state-machine-cat

Examples

{% smcat %}
initial,
"tape player off",
"tape player on" {
  stopped => playing : play;
  playing => stopped : stop;
  playing => paused  : pause;
  paused  => playing : pause;
  paused  => stopped : stop;
};

initial           => "tape player off";
"tape player off" => stopped           : power;
"tape player on"  => "tape player off" : power;
{% endsmcat %}

Configuration

Config	Default	Description
input-type	smcat	Input type. `smcat
engine	dot	Layout engine to use. `dot
direction	top-down	Direction of the state machine diagram. `top-down

Svgbob

Prerequisites

• Install cargo
• Install svgbob_cli

$ sudo apt install cargo
$ cargo install svgbob_cli

Configuration

Config	Default	Description
font-family	arial	Font
font-size	12	Font size
scale	1	Scale the entire svg (dimensions, font size, stroke width)
stroke-width	2	stroke width for all lines

Syntrax

Prerequisites

• Install Pango, Cairo and PangoCairo
• Install syntrax

$ sudo apt install libpango1.0-dev python3-cairo python3-gi
$ pip3 install syntrax

Examples

{% syntrax %}
indentstack(10,
  line(opt('-'), choice('0', line('1-9', loop(None, '0-9'))),
    opt('.', loop('0-9', None))),

  line(opt(choice('e', 'E'), choice(None, '+', '-'), loop('0-9', None)))
)
{% endsyntrax %}

Configurations

Config	Default	Description
scale	1	Scale image
style	unspecified	Style config file
transparent	false	Transparent background

Vega

Prerequisites

Install vega-cli and vega-lite.

$ npm install -g vega-cli vega-lite

The you can use vega and vegalite tag.

Configurations

Config	Default	Description
scale	1	Scale image[Number]

Wavedrom

Prerequisites

Install wavedrom-cli.

$ npm install -g wavedrom-cli

Examples

{% wavedrom %}
{signal: [
  {name: 'clk', wave: 'p.....|...'},
  {name: 'dat', wave: 'x.345x|=.x', data: ['head', 'body', 'tail', 'data']},
  {name: 'req', wave: '0.1..0|1.0'},
  {name: 'ack', wave: '1.....|01.'}
]}
{% endwavedrom %}

Contributing

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

License

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