Improve your documentation with Mermaid.js diagrams

By Chris Metz and Tim Bannister

Topics covered in this blog.

Live editor link: Topics Covered

Why are diagrams useful for documentation?

• Friendly landing spot. Greeting readers with a page full of text can be intimidating to those new to Kubernetes, software engineering and tech writing.

• Faster grasp of concepts. A diagram can serve as a visual roadmap for details covered in the accompanying text.

• Better retention. Humans remember pictures better than words.

Most importantly, readers acquire the confidence to explore further. “Wow! Okay I get this. What’s next? Maybe I can contribute.”

There are many drawing tools to choose from. Traditionally, you create a diagram, save it as png or svg file and then embed the file in the documentation. This takes time, skills vary, and complicates collaboration between contributors and reviewers.

What if we told you there is a package that allows you to generate simple diagrams using a Markdown-like syntax?

Mermaid.js

Mermaid is a package for generating diagrams using markdown-ish text in markdown files. Here are some of the features we love about Mermaid:

• Inline code syntax you can copy into the page markdown. Indeed, you should treat Mermaid code as documentation text subject to the usual PR processes.

• On-line live editor to dynamically create and edit diagrams. The live editor displays the code and the rendered diagram. TIP: You should always use the live editor to draw diagrams.

• Share diagram URLs. The live editor generates a URL for each saved diagram. You can share this link with colleagues to collaborate on diagram creation and editing.

• Generate svg image files. If your site doesn’t support Mermaid, but can handle svg image files as most do, then just ask the live editor to generate an svg file. HINT: we use svg files in this blog because the contributor-site does not support Mermaid.

You can choose from different formats including flowchart, sequence and state. The main Kubernetes website is set up so that Mermaid works out of the box.

The Mermaid documentation is excellent - simple text, multiple examples and diagrams included!

What do I need to start using Mermaid?

You need your favorite markdown editor, live editor access and familiarity with Hugo.

Examples

The first diagram is shown in What is Ingress?

Live editor link: What is Ingress?

Code:

graph LR;
 client([client])-. Ingress-managed <br> load balancer .->ingress[Ingress];
 ingress-->|routing rule|service[Service];
 subgraph cluster
 ingress;
 service-->pod1[Pod];
 service-->pod2[Pod];
 end
 classDef plain fill:#ddd,stroke:#fff,stroke-width:4px,color:#000;
 classDef k8s fill:#326ce5,stroke:#fff,stroke-width:4px,color:#fff;
 classDef cluster fill:#fff,stroke:#bbb,stroke-width:2px,color:#326ce5;
 class ingress,service,pod1,pod2 k8s;
 class client plain;
 class cluster cluster;

Did you notice that some of the diagram elements are colored blue? That is accomplished using a classDef statement to define a class of style attributes, and a class statement to apply that style to those elements.

In the code for the diagram above, we have examples of both:

classDef k8s fill:#326ce5,stroke:#fff,stroke-width:4px,color:#fff; // defines style for the k8s class
class ingress,service,pod1,pod2 k8s; // k8s class is applied to elements ingress, service, pod1 and pod2.

You can even style an individual element in your diagram using the style statement.

style box1 fill:#FF0000,stroke:333,stroke-width:3px // applies style to box1

The next diagram appears in Pod Topology Spread Constraints.

Live editor link: Pod Topology Spread Constraints

Code:

graph TB
subgraph "zoneB"
   p3(Pod) --> n3(Node3)
   n4(Node4)
end
subgraph "zoneA"
   p1(Pod) --> n1(Node1)
   p2(Pod) --> n2(Node2)
end
 
classDef plain fill:#ddd,stroke:#fff,stroke-width:4px,color:#000;
classDef k8s fill:#326ce5,stroke:#fff,stroke-width:4px,color:#fff;
classDef cluster fill:#fff,stroke:#bbb,stroke-width:2px,color:#326ce5;
class n1,n2,n3,n4,p1,p2,p3 k8s;
class zoneA,zoneB cluster;

A recent talk at Kubecon suggested the use of sequence diagrams to describe the interactions between different components in the control plane and nodes. Here is an example illustrating the system flow starting with a kubectl apply command and ending with container startup on the node.

Live editor link: K8s System Flow Sequence Diagram

Code:

%%{init:{"theme":"neutral"}}%% // init directive for theme
sequenceDiagram
    actor me
    participant apiSrv as control plane<br><br>api-server
    participant etcd as control plane<br><br>etcd datastore
    participant cntrlMgr as control plane<br><br>controller<br>manager
    participant sched as control plane<br><br>scheduler
    participant kubelet as node<br><br>kubelet
    participant container as node<br><br>container<br>runtime
    me->>apiSrv: 1. kubectl create -f pod.yaml
    apiSrv-->>etcd: 2. save new state
    cntrlMgr->>apiSrv: 3. check for changes
    sched->>apiSrv: 4. watch for unassigned pods(s)
    apiSrv->>sched: 5. notify about pod w nodename=" "
    sched->>apiSrv: 6. assign pod to node
    apiSrv-->>etcd: 7. save new state
    kubelet->>apiSrv: 8. look for newly assigned pod(s)
    apiSrv->>kubelet: 9. bind pod to node
    kubelet->>container: 10. start container
    kubelet->>apiSrv: 11. update pod status
    apiSrv-->>etcd: 12. save new state

Mermaid provides a simple, open and transparent tool for the community to add, edit and collaborate on diagrams for new or existing documentation.

We hope this blog inspires you to create and include diagrams in your documentation. New and experienced readers and contributors will thank you.

Mermaid rocks!!

• ← Previous
Next →