Edit this page
Report an issueDiagrams in the docs
The Kong Docs include built-in support for mermaid.js. This tool lets you build diagrams directly in Markdown without needing any extra diagram software.
We recommend using Mermaid’s online editor to write your diagrams and see the output side-by-side. When you’re happy with it, copy the code and paste it directly into a docs markdown file.
Tip: If you want to see what the diagram will look like in the docs, use this sample chart with styling config instead, and switch the Theme in the top menu to light mode.
The most commonly used diagram types in the Kong docs are the flowchart and the sequence diagram. You can cover most use cases with these two types. Follow mermaid.js’s docs to learn about node and link styles for each diagram.
If you run into node or link positioning issues in flowcharts, try to rearrange the elements in the chart, link them in different ways, or change the direction of the chart. You can also use subgraphs to help with positioning.
Add a diagram to the docs
To add a diagram to a doc, declare it with the {% mermaid %} and {% endmermaid %} tags.
Here’s an example of a flowchart with links to the final decisions:
{% mermaid %}
flowchart TD
%% this section defines the node and their labels
A{Deployment type?}
B(Traditional mode)
C(Hybrid mode)
D(DB-less mode)
E(Konnect DP)
F{Enough hardware to
run another cluster?}
G(Upgrade CP first)
H(Upgrade DP second)
I([Dual-cluster upgrade])
J([In-place upgrade])
K([Rolling upgrade])
%% this section defines all the connections between nodes
A --> B
A --> C
A --> D
A --> E
B ---> F
C --> G & H
D ----> K
E ----> K
G --> F
F ---Yes--->I
F ---No--->J
H ---> K
%% this section defines node interactions
click K "/gateway/latest/upgrade/rolling-upgrade/"
click I "/gateway/latest/upgrade/dual-cluster/"
click J "/gateway/latest/upgrade/in-place/"
{% endmermaid %}
The code above creates the following diagram:
flowchart TD
%% this section defines the nodes
A{Deployment type?}
B(Traditional mode)
C(Hybrid mode)
D(DB-less mode)
E(Konnect DP)
F{Enough hardware to
run another cluster?}
G(Upgrade CP first)
H(Upgrade DP second)
I([Dual-cluster upgrade])
J([In-place upgrade])
K([Rolling upgrade])
%% this section defines all the connections between nodes
A --> B
A --> C
A --> D
A --> E
B ---> F
C --> G & H
D ----> K
E ----> K
G --> F
F ---Yes--->I
F ---No--->J
H ---> K
%% this section defines node interactions
click K "/gateway/latest/upgrade/rolling-upgrade/"
click I "/gateway/latest/upgrade/dual-cluster/"
click J "/gateway/latest/upgrade/in-place/"
Styling
All diagrams built with mermaid.js have built-in styling.
If you need to adjust styling, you can set styles in the diagram definition with
the style tag for nodes, or the linkStyle tag for lines.
Tip: Since links (aka lines or connectors) don’t have names/IDs like nodes do, you have to style links by numbering them. It can be difficult to tell what order the links are in, and which connector the style will apply to. Mermaid’s online editor lets you test this out in real time, so you can quickly figure out the numbers.
To avoid having to reshuffle anything or re-figure out the numbers, apply link styling after you have added all the nodes and links to your diagram.
Here are some basic style tags to know:
-
fill: The background color of an element -
stroke: The line color of an element. For a node, this refers to a border color; for a link, this refers to its line color. -
stroke-dasharray: Turns the border of a node into a dashed line.Note that you don’t need to do this for links, as you can specify a dotted link by using
-.->instead of-->.
Here’s some examples of these styles in use:
style API stroke:none
# Removes the border from the API node
style DBX stroke-dasharray:3
# Turns the border of the DBX node into a dashed line
style Admin fill:none,stroke:none,color:#d44324
# Removes the fill and border of the admin node and changes the text colour to the hex code above
linkStyle 4,7 stroke:#d44324,color:#d44324
# Changes the line and text color of the 4th and 7th connectors in the diagram
linkStyle 3,6,9 stroke:#b6d7a8
# Changes the line color of the 3rd, 6th, and 9th connectors in the diagram
These styles are all used to create the following diagram:
Export a Mermaid diagram from the docs
You can export a Mermaid diagram from the Kong docs using the Mermaid live editor. This method will only work with diagrams that don’t contain icons or images.
- Copy the Mermaid diagram from the Kong doc file. You can find the doc source file by clicking Edit this page at the top right corner of the doc.
- Paste the Mermaid diagram into the Mermaid live editor.
- If the diagram contains images, remove all
<img>tags. - Replace any Liquid variables (for example,
{{site.base_gateway}}) with their output. Liquid variables won’t render correctly in the Mermaid live editor. - Click Actions on the bottom left corner and select the file type you want to export the diagram to.
