jekyll-diagrams

jekyll-diagrams

A Jekyll plugin with support for Blockdiag, Erd, GraphViz, Mermaid, Nomnoml, PlantUML, Svgbob, Syntrax, Vega, Vega-Lite and WaveDrom.

Jekyll Diagrams

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

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

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.