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

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

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

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

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

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

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

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

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.