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
- 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.