Jekyll Diagrams

Jekyll Diagrams is a jekyll plugins for creating diagrams, it is inspired by asciidoctor-diagram. Currently support:

• Blockdiag
• Erd
• GraphViz
• Mermaid
• Nomnoml
• PlantUML
• Svgbob
• Syntrax
• Vega
• Vega-Lite
• WaveDrom.

WARNING: Since it is just 0.x.x currently, internal implementation maybe CHANGED FREQUENTLY. So don't rely on the internal implementation unless you know what you are doing.

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
• Configurations
  • Error Mode
• 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

Configurations

Configurations can be set in your site's config file under jekyll-diagrams key as below:

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

You can override global config in the front matter of each page, e.g.

---
title: Custom configurations per page

jekyll-diagrams:
  graphviz:
    # configurations for graphviz
---

# Your content

Error Mode

You can use error_mode to configure how to response to errors. jekyll-diagrams respect the global liquid options:

liquid:
  error_mode: 'mode'

Avaliable options:

• lax: Ignore all errors
• warn: Output a warning on the console for each error
• strict: Output an error message and stop the build

You can also override it for just jekyll-diagrams:

jekyll-diagrams:
  error_mode: 'mode'

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

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 layout engine
graph_attributes	unspecified	Set default graph attributes
node_attributes	unspecified	Set default node attributes
edge_attributes	unspecified	Set default edge attributes
encoding	utf-8	Set default SVG encoding

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

Mermaid

Prerequisites

Install mermaid.cli.

$ npm install -g mermaid.cli

Notice: You may need to install some missing libraries, follow the output of mmdc.

Examples

{% mermaid %}
sequenceDiagram
    participant John
    participant Alice
    Alice->>John: Hello John, how are you?
    John-->>Alice: Great!
{% endmermaid %}

Configurations

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

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 scxml json
engine	dot	Layout engine to use. dot circo fdp neato osage twopi
direction	top-down	Direction of the state machine diagram. top-down bottom-top left-right right-left

Svgbob

Prerequisites

Install svgbob_cli.

$ sudo apt install cargo
$ cargo install svgbob_cli

Examples

{% svgbob %}
                           .--->  F
  A       B      C  D     /
  *-------*-----*---*----*----->  E
           \            ^ \
            v          /   '--->  G
             B --> C -'
{% endsvgbob %}

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 support
• Install syntrax

$ sudo apt install libpango1.0-dev python3-cairo python3-gi python3-gi-cairo
$ 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.

Examples

{% vegalite %}
{
  "": "https://vega.github.io/schema/vega-lite/v4.json",
  "description": "A simple bar chart with embedded data.",
  "data": {
    "values": [
      {"a": "A", "b": 28}, {"a": "B", "b": 55}, {"a": "C", "b": 43},
      {"a": "D", "b": 91}, {"a": "E", "b": 81}, {"a": "F", "b": 53},
      {"a": "G", "b": 19}, {"a": "H", "b": 87}, {"a": "I", "b": 52}
    ]
  },
  "mark": "bar",
  "encoding": {
    "x": {"field": "a", "type": "ordinal"},
    "y": {"field": "b", "type": "quantitative"}
  }
}
{% endvegalite %}

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.