Mermaid is a package for generating figures using simple markdown-like syntax in markdown files. This document explains how you can use Mermaid to create and add figures to your K8s docs contributions. It includes multiple examples, live-editor references and three methods for generating and embedding Mermaid figures inside your documentation.
The target audience for this document is anybody wishing to learn about Mermaid and/or how to create and add figures to Kubernetes documentation.
- Basic understanding of markdown.
- Using the Mermaid live editor.
- How to use Hugo shortcodes.
- Procedures to perform local preview build.
-
Sveidqvist, K., Jain, A. (2021). The Official Guide to Mermaid.js. MermaidPress
-
Diagrams improve documentation clarity and comprehension.
-
Simple, inline code syntax you add to the markdown file.
-
Included in K8s docs and docsy theme.
-
On-line live editor to create and edit figures.
-
Live editor generates a link beginning for each figure. You can share this link with colleagues to collaborate on figure creation and editing.
Live editor links begin with https://mermaid-js.github.io/mermaid-live-editor/edit.
- Figure updates are simple: just open a PR and edit the mermaid code in the respective markdown file.
Basically, Mermaid provides a simple, open and transparent method for the community to add, edit and collaborate on figures for new or existing documents.
This section contains examples of Mermaid figures currently used in K8s docs. Each example includes the docs page where the figure is rendered, a link to the repo source markdown file, live editor link, the actual figure and the mermaid code.
K8s documentation encapsulates mermaid code in the hugo {{< mermaid >}}/{{< /mermaid >}} shortcode. I have omitted the shortcode in the code examples so that you can more easily cut/paste with the live-editor.
Docs page: Contribute to K8s docs
K8s/website repo file link: ../contribute/_index.md
Live editor link: figure
Figure:
Code:
flowchart TB
subgraph third[Open PR]
direction TB
U[ ] -.-
Q[Improve content] --- N[Create content]
N --- O[Translate docs]
O --- P[Manage/publish docs parts<br>of K8s release cycle]
end
subgraph second[Review]
direction TB
T[ ] -.-
D[Look over the<br>K8s/website<br>repository] --- E[Check out the<br>Hugo static site<br>generator]
E --- F[Understand basic<br>GitHub commands]
F --- G[Review open PR<br>and change review <br>processes]
end
subgraph first[Sign up]
direction TB
S[ ] -.-
B[Sign the CNCF<br>Contributor<br>License Agreement] --- C[Join sig-docs<br>Slack channel]
C --- V[Join kubernetes-sig-docs<br>mailing list]
V --- M[Attend weekly<br>sig-docs calls<br>or slack meetings]
end
A([fa:fa-user New<br>Contributor]) --> first
A --> second
A --> third
A --> H[Ask Questions!!!]
classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000
class A,B,C,D,E,F,G,H,M,Q,N,O,P,V grey
class S,T,U spacewhite
class first,second,third white
Docs page: What is Ingress
K8s/website repo file link: ingress.md
Live editor link: figure
Figure:
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;
Docs page: Pod Topology Spread Constraints#node labels
K8s/website repo file link: ../docs/concepts/workloads/pods/pod-topology-spread-constraints.md
Live editor link: figure
Figure:
Code:
graph TB
subgraph "zoneB"
n3(Node3)
n4(Node4)
end
subgraph "zoneA"
n1(Node1)
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 k8s;
class zoneA,zoneB cluster;
Docs page: Example: OneTopologySpreadConstraint // first figure on this page
K8s/website repo file link: ../docs/concepts/workloads/pods/pod-topology-spread-constraints.md
Live editor link: figure
Figure:
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;
Sequence diagrams describe a series of actions between components that result in a completed task. You can use Mermaid to create sequence diagrams.
Here is a sequence diagram describing pod creation and container startup.
Live editor link: figure
Code:
%%{init:{"theme":"neutral"}}%%
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
You have three methods for adding Mermaid figures to K8s docs: Hugo Mermaid shortcode, hybrid Mermaid+SVG and docsy theme support.
The figure below lays out the three methods:
Live editor link to the 3 methods figure
K8s docs supports a Hugo shortcode for handling Mermaid figures.
-
Use live editor to create and edit figures.
-
Implemented and used for existing K8s docs Mermaid figures.
-
Easy to use by wrapping Mermaid code inside
{{< mermaid >}} … {{</ mermaid >}}shortcode tags. -
In-line Mermaid code so contributors/reviewers can edit on the fly.
Note: Add the live editor URL link as a comment in your code so contributors/reviewers can view/edit/test your mermaid code and figures.
K8s docs support SVG images. This method allows you to create/edit Mermaid figures in the live editor. Then from the live editor, you generate and download an SVG image file. Finally, add the SVG image to the docs as you would with any other SVG image.
-
Use live editor to create and edit figures.
-
Use live editor to generate and download SVG image.
-
No change to existing K8s docs SVG image configuration.
-
Leverage new Mermaid features available in the live editor. Those features might not be available in the current K8s/website version. Check PRs or repo code to find out the Mermaid version supported in the K8s docs.
-
Mermaid code is de-coupled from the K8s docs. In other words, new or edited figures show up in PRs and code as SVG images, not in-line Mermaid code.
Note: Add the live editor URL link as a comment block in the SVG file using your favorite text editor. Contributors/reviewers can then view/edit the mermaid code.
To add a comment to the SVG image file, use a text editor and add something like the following:
<!-- To view or edit the mermaid code, use the following URL: -->
<!-- https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb ... -->
Note: Check PRs to see if K8s docs has enabled docsy theme Mermaid support.
-
Use live editor to create and edit figures.
-
Easy to use by inserting Mermaid code inside a code block using
mermaid …. -
No need for shortcode tags.
-
Inherits current Mermaid version from docsy.dev submodule.
-
In-line Mermaid code so contributors/reviewers can edit on the fly.
Note: Add the live editor URL link as a comment in your code so contributors/reviewers can view/edit/test the mermaid code.
If you wish to create, edit and add figures to K8s docs right now, you can use the Hugo shortcode or Hybrid Mermaid+SVG methods. Check PRs for docsy theme support.
Regardless of which method you choose, you should:
-
Use the live editor to create and edit figures.
-
Add the figure's live editor link to a comment in the markdown file or in the SVG image file.
You can share figures using functions included with the live editor.
-
Generate and send SVG image files.
-
Generate and send URL links pointing to the SVG image.
-
Generate and send URL links to pointing to the figure's mermaid code.
You might use this method to show a colleague a quick preview of an image you are working on. Or you could use the Hybrid+SVG method to add figures to your content.
The following figure outlines the general workflow for sharing SVG images with the live editor.
Use the following procedures to share SVG or PNG images.
-
Create a figure in the live editor.
-
Under history, save the figure. This generates a unique live editor link for the figure and code. You should save this link in case you need to modify the image later.
NOTE: The current state of the figure generated from the </> Code is saved.
- Under action, you have several options.
-
Copy the image to clipboard then paste it to your favorite message or email app.
-
Generate a link to the SVG image. Note this is NOT the link to the live editor mermaid figure and code contained in your browser’s URL field. The SVG image pointers begin with
https://mermaid.ink/img/.
K8s docs not support markdown links to external figures.
- Download the SVG image file. If you use the image in your documentation, don’t forget to add the live editor link in a comment block to the SVG image file.
You can use the same procedures to share a PNG file with the exception that you cannot edit the file to add a live editor link. You would need to place the live editor link in a comment before or after the PNG, just as you would with in-line Mermaid code.
The live editor generates a unique link for each new and edited figure. This enables colleagues to share links for each new or edited version of a figure.
The link begins with the https://mermaid-js.github.io/mermaid-live-editor/edit prefix and the entire link is shown in your browser's URL field.
You should use the live editor link if you, and one or more colleagues, are collaborating on a figure.
The following figure outlines the general workflow for sharing live editor links.
Use the following procedures to generate and share live editor links.
-
Create a figure in the live editor.
-
Under history, save the figure. This generates a unique live editor link for this figure. You MUST save the figure to generate the live editor link you will share with colleagues.
-
Send the live editor link to your colleagues. This link is shown in the URL field of your browser and begins with
https://mermaid-js.github.io/mermaid-live-editor/edit. -
When you receive a live editor link, click it and the live editor will open and show the code and figure. After you make any edits, repeat step 2 and step 3 above to save the figure and send out the new live editor link.