图表指南

本指南向您展示如何使用 Mermaid JavaScript 库创建、编辑和分享图表。Mermaid.js 允许您在 Markdown 文件中使用类似于 markdown 的简单语法生成图表。您还可以使用 Mermaid 生成 .svg 或 .png 图像文件，并将其添加到文档中。

本指南的目标受众是任何希望了解 Mermaid 以及如何为 Kubernetes 文档创建和添加图表的人员。

图 1 概述了本节涵盖的主题。

图 1. 本节涵盖的主题。

开始使用 Mermaid 所需具备的基础：

• 对 markdown 有基本了解。
• 使用 Mermaid 实时编辑器。
• 使用 Hugo 短代码 (shortcodes)。
• 使用 Hugo {{< figure >}} 短代码。
• 执行 Hugo 本地预览。
• 熟悉 贡献新内容 的流程。

为什么你应该在文档中使用图表

图表可以提高文档的清晰度和理解度。对于用户和贡献者来说都有优势。

用户受益包括：

• 友好的着陆页。详细的纯文本欢迎页面可能会让用户感到畏缩，特别是初次使用 Kubernetes 的用户。
• 更快地掌握概念。图表可以帮助用户理解复杂主题的关键点。您的图表可以作为视觉学习指南，帮助用户深入了解主题详情。
• 更好的记忆效果。对某些人来说，回忆图片比回忆文本更容易。

贡献者受益包括：

• 协助开发贡献内容的结构和内容。例如，您可以从涵盖高层要点的简单图表开始，然后深入探讨细节。
• 扩大和增加用户社区。辅以图表且易于消化的文档会吸引新用户，这些用户以前可能因为感知到的复杂性而不愿参与。

您应该考虑您的目标受众。除了经验丰富的 K8s 用户外，还有许多初学者。即使是简单的图表也能帮助新用户吸收 Kubernetes 概念。这使他们更有信心进一步探索 Kubernetes 及其文档。

Mermaid

Mermaid 是一个开源 JavaScript 库，它允许您在 Markdown 文件中配置内联的类似 markdown 的简单语法来创建、编辑和轻松分享图表。

以下是 Mermaid 的功能列表：

• 简单的代码语法。
• 包含基于 Web 的工具，允许您编写代码并预览图表。
• 支持多种格式，包括流程图、状态图和时序图。
• 通过分享每个图表的 URL 轻松与同事协作。
• 广泛的形状、线条、主题和样式选择。

以下是使用 Mermaid 的优势：

• 无需单独的非 Mermaid 图表工具。
• 符合现有的 PR 工作流程。您可以将 Mermaid 代码视为包含在 PR 中的 Markdown 文本。
• 简单的工具构建简单的图表。您不希望陷入制作过于复杂和详细图片的困境。保持简单！

Mermaid 为 SIG 社区提供了一种简单、开放且透明的方法，用于为新文档或现有文档添加、编辑图表及协作。

实时编辑器

Mermaid 实时编辑器 是一个基于 Web 的工具，使您能够创建、编辑和评审图表。

以下是实时编辑器的功能列表：

• 显示 Mermaid 代码和渲染后的图表。
• 为每个保存的图表生成 URL。URL 显示在浏览器的地址栏中。您可以与同事分享该 URL，他们可以访问并修改图表。
• 可选择下载 .svg 或 .png 文件。

创建图表的方法

图 2 概述了生成和添加图表的三种方法。

图 2. 创建图表的方法。

内联 (Inline)

图 3 概述了使用内联方法添加图表的步骤。

图 3. 内联方法步骤。

以下是使用内联方法添加图表应遵循的步骤：

1. 使用实时编辑器创建图表。
2. 将图表 URL 存储在某处以便以后访问。
3. 将 Mermaid 代码复制到 .md 文件中您希望图表出现的位置。
4. 使用 Markdown 文本在图表下方添加说明文字。

Hugo 构建会运行 Mermaid 代码并将其转换为图表。

以下是 .md 文件中包含的代码片段示例：

---
title: My PR
---
Figure 17 shows a simple A to B process.
some markdown text
...
{{< mermaid >}} 
    graph TB
    A --> B
{{< /mermaid >}}

Figure 17. A to B
more text

有关图表说明文字的更多详细信息，请参阅 如何使用说明文字。

以下是内联方法的优势：

• 实时编辑器工具。
• 易于在实时编辑器和您的 .md 文件之间复制 Mermaid 代码。
• 无需处理单独的 .svg 图像文件。
• 内容文本、图表代码和图表说明文字都包含在同一个 .md 文件中。

您应该使用 本地 和 Netlify 预览来验证图表是否正确渲染。

Mermaid+SVG

图 4 概述了使用 Mermaid+SVG 方法添加图表的步骤。

图 4. Mermaid+SVG 方法步骤。

以下是使用 Mermaid+SVG 方法添加图表应遵循的步骤：

1. 使用实时编辑器创建图表。
2. 将图表 URL 存储在某处以便以后访问。
3. 为图表生成 .svg 图像文件并将其下载到适当的 images/ 文件夹中。
4. 使用 {{< figure >}} 短代码在 .md 文件中引用图表。
5. 使用 {{< figure >}} 短代码的 caption 参数添加说明文字。

例如，使用实时编辑器创建一个名为 boxnet 的图表。将图表 URL 存储在某处以便以后访问。生成并下载 boxnet.svg 文件到适当的 ../images/ 文件夹。

在 PR 的 .md 文件中使用 {{< figure >}} 短代码引用 .svg 图像文件并添加说明文字。

{{< figure src="/static/images/boxnet.svg" alt="Boxnet figure" class="diagram-large" caption="Figure 14. Boxnet caption" >}}

有关图表说明文字的更多详细信息，请参阅 如何使用说明文字。

您应该使用文本编辑器在 .svg 图像文件中以注释块的形式添加实时编辑器 URL。例如，您可以在 .svg 图像文件的开头包含以下内容：

<!-- To view or edit the mermaid code, use the following URL: -->
<!-- https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb ... <remainder of the URL> -->

以下是 Mermaid+SVG 方法的优势：

• 实时编辑器工具。
• 实时编辑器工具支持最新的 Mermaid 功能集。
• 采用现有的 kubernetes/website 处理 .svg 图像文件的方法。
• 环境不需要 Mermaid 支持。

务必使用 本地 和 Netlify 预览检查您的图表是否正确渲染。

外部工具

图 5 概述了使用外部工具方法添加图表的步骤。

首先，使用外部工具创建图表并将其保存为 .svg 或 .png 图像文件。之后，使用与 Mermaid+SVG 方法相同的步骤添加图像文件。

图 5. 外部工具方法步骤

以下是使用外部工具方法添加图表应遵循的步骤：

1. 使用外部工具创建图表。
2. 保存图表坐标以便贡献者访问。例如，您的工具可能会提供图表图像的链接，或者您可以将源代码文件（如 .xml 文件）放在公共仓库中，以便贡献者以后访问。
3. 生成图表并将其保存为 .svg 或 .png 图像文件。将此文件下载到适当的 ../images/ 文件夹。
4. 使用 {{< figure >}} 短代码在 .md 文件中引用图表。
5. 使用 {{< figure >}} 短代码的 caption 参数添加说明文字。

以下是 images/apple.svg 图表的 {{< figure >}} 短代码示例：

{{< figure src="/static/images/apple.svg" alt="red-apple-figure" class="diagram-large" caption="Figure 9. A Big Red Apple" >}} 

如果您的外部绘图工具允许：

• 您可以将多个 .svg 或 .png 徽标、图标和图像合并到您的图表中。但是，请确保遵守版权并遵循 Kubernetes 文档关于使用第三方内容的 指南。
• 您应该保存图表源坐标，以便以后贡献者访问。例如，您的工具可能会提供图表图像的链接，或者您可以将源代码文件（如 .xml 文件）放在某处供贡献者访问。

有关 K8s 和 CNCF 徽标及图像的更多信息，请查看 CNCF 艺术资产 (Artwork)。

以下是外部工具方法的优势：

• 贡献者熟悉外部工具。
• 图表需要比 Mermaid 所能提供的更多的细节。

不要忘记使用 本地 和 Netlify 预览检查您的图表是否正确渲染。

示例

本节展示了几个 Mermaid 图表示例。

示例 1 - Pod 拓扑分布约束

图 6 显示了出现在 Pod 拓扑分布约束 页面中的图表。

图 6. Pod 拓扑分布约束。

代码块

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;

示例 2 - Ingress

图 7 显示了出现在 什么是 Ingress 页面中的图表。

代码块

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;

示例 3 - K8s 系统流程

图 8 描绘了一个 Mermaid 时序图，显示了 K8s 组件之间启动容器的系统流程。

代码块

%%{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

如何设置图表样式

您可以使用著名的 CSS 命名法为一种或多种图表元素设置样式。您可以通过在 Mermaid 代码中使用两种类型的语句来实现这一点：

• classDef 定义一类样式属性。
• class 定义一个或多个应用该类的元素。

在 图 7 的代码中，您可以看到两者的示例。

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.

您可以在图表中包含一个或多个 classDef 和 class 语句。您还可以在图表中使用官方 K8s 组件的 #326ce5 十六进制颜色代码。

有关样式和类的更多信息，请参阅 Mermaid 样式和类文档。

如何使用说明文字 (Captions)

说明文字是图表的简短描述。图表的标题或简短描述都是说明文字的例子。说明文字并不是要取代文档中的解释性文本。相反，它们作为该文本与图表之间的“上下文链接”。

将一些文本和通过说明文字绑定在一起的图表相结合，有助于为您希望传达给用户的信息提供简明表示。

如果没有说明文字，您就是在要求用户扫描图表上方或下方的文本来弄清楚其含义。这对用户来说可能会感到沮丧。

图 9 列出了正确添加说明文字的三个组件：图表、图表说明文字和图表引用 (referral)。

图表

Mermaid+SVG 和 外部工具 方法生成 .svg 图像文件。

以下是定义在保存在 /images/docs/components-of-kubernetes.svg 的 .svg 图像文件中的图表的 {{< figure >}} 短代码：

{{< figure src="/images/docs/components-of-kubernetes.svg" alt="Kubernetes pod running inside a cluster" class="diagram-large" caption="Figure 4. Kubernetes Architecture Components" >}}

您应该将 src、alt、class 和 caption 值传递到 {{< figure >}} 短代码中。您可以使用 diagram-large、diagram-medium 和 diagram-small 类来调整图表的大小。

有关创建图表的不同方法的更多信息，请参阅 创建图表的方法。

图表说明文字

接下来，添加图表说明文字。

如果您在 .svg 图像文件中定义图表，那么您应该使用 {{< figure >}} 短代码的 caption 参数。

{{< figure src="/images/docs/components-of-kubernetes.svg" alt="Kubernetes pod running inside a cluster" class="diagram-large" caption="Figure 4. Kubernetes Architecture Components" >}}

如果您使用内联 Mermaid 代码定义图表，那么您应该使用 Markdown 文本。

Figure 4. Kubernetes Architecture Components

以下是添加图表说明文字时需要考虑的几点：

• 使用 {{< figure >}} 短代码为 Mermaid+SVG 和 外部工具 图表添加图表说明文字。
• 使用简单的 Markdown 文本为 内联 方法添加图表说明文字。
• 在图表说明文字前加上 图 编号.。您必须使用 图，并且编号对于文档页面中的每个图表必须是唯一的。在编号后添加一个句点。
• 在同一行的 图 编号. 之后添加您的图表说明文本。您必须以句点结束说明文字。保持说明文本简短。
• 将您的图表说明文字放在图表 下方。

图表引用 (Referral)

最后，您可以添加图表引用。这在您的文本内部使用，并且应该位于图表本身之前。它允许用户将您的文本与关联的图表连接起来。引用和说明文字中的 图 编号 必须匹配。

您应该避免使用空间引用，例如 ..下图.. 或 ..下表..。

以下是图表引用的示例：

Figure 10 depicts the components of the Kubernetes architecture.
The control plane ...

图表引用是可选的，在某些情况下可能不合适。如果您不确定，请在文本中添加图表引用，看看外观和读起来是否可以。如有疑问，请使用图表引用。

完整图示

图 10 展示了 Kubernetes 架构图，其中包括图表、图表说明文字和图表引用。{{< figure >}} 短代码渲染图表、添加说明文字，并包含可选的 link 参数以便您可以为图表添加超链接。图表引用包含在本段中。

以下是此图表的 {{< figure >}} 短代码示例：

{{< figure src="/images/docs/components-of-kubernetes.svg" alt="Kubernetes pod running inside a cluster" class="diagram-large" caption="Figure 10. Kubernetes Architecture." link="https://kubernetes.ac.cn/docs/concepts/overview/components/" >}}

技巧

• 始终使用实时编辑器来创建/编辑图表。

• 始终使用 Hugo 本地和 Netlify 预览来查看图表在文档中的外观。

• 包含图表源指针，如 URL、源代码位置，或指明代码是自文档化的。

• 始终使用图表说明文字。

• 在 Issue 和 PR 中包含图表 .svg 或 .png 图像和/或 Mermaid 源代码非常有帮助。

• 对于 Mermaid+SVG 和 外部工具 方法，请使用 .svg 图像文件，因为放大图表时它们能保持清晰。

• 对于 .svg 文件的最佳实践是将其加载到 SVG 编辑工具中并使用“将文本转换为路径”功能。这可以确保图表在所有系统上呈现相同，无论字体可用性和字体渲染支持如何。

• Mermaid 不支持额外的图标或艺术资产。

• Hugo Mermaid 短代码在实时编辑器中不起作用。

• 每当您在实时编辑器中修改图表时，您必须保存它以生成图表的新 URL。

• 点击本节中的图表可以在实时编辑器中查看代码和图表渲染。

• 查看此页面 diagram-guide.md 的源代码以获取更多示例。

• 查看 Mermaid 文档 以获取解释和示例。

最重要的是，保持图表简单。这将为您和您的贡献者伙伴节省时间，并让新老用户更易于阅读。