圖表指南

本指南說明如何使用 Mermaid JavaScript 程式庫建立、編輯和共用圖表。Mermaid.js 可讓您在 Markdown 檔案內使用類似 Markdown 的簡單語法來產生圖表。您也可以使用 Mermaid 來產生 .svg 或 .png 影像檔案，並將其新增至您的文件中。

本指南的目標讀者是任何想要瞭解 Mermaid 和/或如何建立圖表並將其新增至 Kubernetes 文件的人。

圖 1 概述本節涵蓋的主題。

圖 1. 本節涵蓋的主題。

開始使用 Mermaid，您只需要以下條件

• Markdown 的基本理解。
• 使用 Mermaid 即時編輯器。
• 使用 Hugo shortcodes。
• 使用 Hugo {{< figure >}} shortcode。
• 執行 Hugo 本機預覽。
• 熟悉貢獻新內容流程。

為何您應該在文件中使用圖表

圖表可以提高文件的清晰度和理解度。對於使用者和貢獻者而言，都有優點。

使用者受益包括

• 友善的登陸點。僅包含詳細文字的歡迎頁面可能會讓使用者感到害怕，尤其是 Kubernetes 的初次使用者。
• 更快掌握概念。圖表可以幫助使用者理解複雜主題的重點。您的圖表可以作為視覺學習指南，深入了解主題細節。
• 更好的記憶力。對於某些人來說，記住圖片比記住文字更容易。

貢獻者受益包括

• 協助開發貢獻的結構和內容。例如，您可以從涵蓋高層次重點的簡單圖表開始，然後深入探討細節。
• 擴大和發展使用者社群。易於理解且輔以圖表的文件，可以吸引先前可能因認為複雜而卻步的新使用者。

您應該考慮您的目標受眾。除了經驗豐富的 K8s 使用者之外，您還會有許多 Kubernetes 新手。即使是簡單的圖表也可以幫助新使用者吸收 Kubernetes 的概念。他們會變得更大膽、更有信心進一步探索 Kubernetes 和文件。

Mermaid

Mermaid 是一個開放原始碼 JavaScript 程式庫，可讓您使用類似 Markdown 的簡單語法，以內嵌方式在 Markdown 檔案中設定，來建立、編輯和輕鬆分享圖表。

以下列出 Mermaid 的功能

• 簡單的程式碼語法。
• 包含一個以網頁為基礎的工具，可讓您編寫程式碼並預覽圖表。
• 支援多種格式，包括流程圖、狀態圖和循序圖。
• 透過分享每個圖表的 URL，輕鬆與同事協作。
• 廣泛的形狀、線條、主題和樣式選擇。

以下列出使用 Mermaid 的優點

• 無需個別的非 Mermaid 圖表工具。
• 遵守現有的 PR 工作流程。您可以將 Mermaid 程式碼視為僅包含在 PR 中的 Markdown 文字。
• 簡單的工具建構簡單的圖表。您不會想陷入（重新）製作過於複雜和詳細的圖片。保持簡單！

Mermaid 為 SIG 社群提供了一種簡單、開放和透明的方法，可以為新的或現有的文件新增、編輯和協作圖表。

即時編輯器

Mermaid 即時編輯器 是一個以網頁為基礎的工具，可讓您建立、編輯和檢閱圖表。

以下列出即時編輯器的功能

• 顯示 Mermaid 程式碼和呈現的圖表。
• 為每個儲存的圖表產生一個 URL。URL 會顯示在瀏覽器的 URL 欄位中。您可以與同事分享 URL，他們可以存取和修改圖表。
• 可選擇下載 .svg 或 .png 檔案。

建立圖表的方法

圖 2 概述了產生和新增圖表的三種方法。

圖 2. 建立圖表的方法。

內嵌

圖 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

如需圖表標題的詳細資訊，請參閱如何使用標題。

以下列出內嵌方法的優點

• 即時編輯器工具。
• 易於將 Mermaid 程式碼複製到即時編輯器和您的 .md 檔案，以及從即時編輯器和您的 .md 檔案複製 Mermaid 程式碼。
• 無需個別處理 .svg 影像檔案。
• 內容文字、圖表程式碼和圖表標題都包含在同一個 .md 檔案中。

您應該使用本機和 Netlify 預覽來驗證圖表是否正確呈現。

Mermaid+SVG

圖 4 概述了使用 Mermaid+SVG 方法新增圖表的步驟。

圖 4. Mermaid+SVG 方法的步驟。

以下列出您應該遵循的使用 Mermaid+SVG 方法新增圖表的步驟

1. 使用即時編輯器建立您的圖表。
2. 將圖表 URL 儲存在某處，以便日後存取。
3. 為圖表產生 .svg 影像檔案，並將其下載到適當的 images/ 資料夾。
4. 使用 {{< figure >}} shortcode 來參考 .md 檔案中的圖表。
5. 使用 {{< figure >}} shortcode 的 caption 參數新增標題。

例如，使用即時編輯器建立一個名為 boxnet 的圖表。將圖表 URL 儲存在某處，以便日後存取。產生並下載 boxnet.svg 檔案到適當的 ../images/ 資料夾。

在您 PR 的 .md 檔案中使用 {{< figure >}} shortcode 來參考 .svg 影像檔案並新增標題。

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

如需圖表標題的詳細資訊，請參閱如何使用標題。

注意

shortcode 是將 .svg 影像檔案新增至文件的慣用方法。您也可以使用標準 markdown 影像語法，例如：![my boxnet diagram](static/images/boxnet.svg)。而且您需要在圖表下方新增標題。

您應該使用文字編輯器將即時編輯器 URL 作為註解區塊新增到 .svg 影像檔案中。例如，您會在 .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 方法相同的步驟來新增 .svg 影像檔案。

圖 5. 外部工具方法的步驟

以下列出您應該遵循的使用外部工具方法新增圖表的步驟

1. 使用您的外部工具建立圖表。
2. 儲存圖表座標以供貢獻者存取。例如，您的工具可能會提供圖表影像的連結，或者您可以將原始碼檔案（例如 .xml 檔案）放置在公用儲存庫中，以供日後貢獻者存取。
3. 產生圖表並將其儲存為 .svg 或 .png 影像檔案。將此檔案下載到適當的 ../images/ 資料夾。
4. 使用 {{< figure >}} shortcode 來參考 .md 檔案中的圖表。
5. 使用 {{< figure >}} shortcode 的 caption 參數新增標題。

以下是 images/apple.svg 圖表的 {{< figure >}} shortcode

{{< 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 十六進位色彩代碼來表示 K8s 元件。

如需樣式和類別的更多資訊，請參閱 Mermaid 樣式和類別文件。

如何使用標題

標題是圖表的簡短描述。圖表的標題或簡短描述都是標題的範例。標題並非旨在取代您文件中已有的解釋性文字。相反地，它們作為文字和圖表之間的「上下文連結」。

文字和圖表的組合，再透過標題連結在一起，有助於簡潔地呈現您希望向使用者傳達的資訊。

如果沒有標題，您等於要求使用者掃描圖表上方或下方的文字，以理解其含義。這可能會讓使用者感到沮喪。

圖 9 闡述了正確標題的三個組成部分：圖表、圖表標題和圖表參考。

圖表

Mermaid+SVG 和 External Tool 方法會產生 .svg 影像檔案。

以下是 {{< figure >}} 簡碼，適用於在儲存至 /images/docs/components-of-kubernetes.svg 的 .svg 影像檔案中定義的圖表

{{< 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 類別調整圖表的大小。

注意

使用 Inline 方法建立的圖表不使用

簡碼。Mermaid 程式碼定義了圖表在頁面上的呈現方式。

請參閱建立圖表的方法，以取得建立圖表不同方法的更多資訊。

圖表標題

接下來，新增圖表標題。

如果您在 .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 和 External Tool 圖表新增圖表標題。
• 使用簡單的 Markdown 文字，為 Inline 方法新增圖表標題。
• 在圖表標題前加上 圖 NUMBER.。您必須使用 圖，且號碼在您的文件頁面中每個圖表都必須是唯一的。在號碼後加上句點。
• 在同一行的 圖 NUMBER. 之後，加入您的圖表標題文字。您必須在標題中加上句點。保持標題文字簡短。
• 將圖表標題放在圖表下方。

圖表參考

最後，您可以新增圖表參考。這會在您的文字中使用，並且應該在圖表本身之前。它讓使用者可以將您的文字與相關圖表連結起來。參考和標題中的 圖 NUMBER 必須一致。

您應該避免使用空間參考，例如 ..下方的影像.. 或 ..下圖..

以下是圖表參考的範例

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.dev.org.tw/docs/concepts/overview/components/" >}}

提示

• 始終使用即時編輯器來建立/編輯您的圖表。

• 始終使用 Hugo 本機預覽和 Netlify 預覽來查看圖表在文件中的外觀。

• 包含圖表來源指標，例如 URL、原始碼位置，或指示程式碼是自我編寫文件。

• 始終使用圖表標題。

• 在 issue 和 PR 中包含圖表的 .svg 或 .png 影像和/或 Mermaid 原始碼非常有幫助。

• 對於 Mermaid+SVG 和 External Tool 方法，請使用 .svg 影像檔案，因為當您放大圖表時，它們仍保持清晰。

• .svg 檔案的最佳做法是將其載入 SVG 編輯工具，並使用「將文字轉換為路徑」功能。這可確保圖表在所有系統上呈現相同，無論字型可用性和字型呈現支援如何。

• Mermaid 不支援其他圖示或美術作品。

• Hugo Mermaid 簡碼在即時編輯器中無法運作。

• 每當您在即時編輯器中修改圖表時，您必須儲存它，才能為圖表產生新的 URL。

• 按一下本節中的圖表，以在即時編輯器中查看程式碼和圖表呈現。

• 查看此頁面的原始碼 diagram-guide.md，以取得更多範例。

• 查看 Mermaid 文件，以取得說明和範例。

最重要的是，保持圖表簡潔。這將為您和同仁貢獻者節省時間，並讓新手和經驗豐富的使用者更容易閱讀。