圖表語法

Mermaid 的語法用於建立圖表。你會發現它並不太難，一天就能學會。接下來的章節將深入探討每種圖表類型的語法。

語法、部署和設定共同構成 Mermaid 的整體。

圖表範例可以在Mermaid 線上編輯器中找到，它也是一個很棒的練習區域。

語法結構

大家會注意到，所有的圖表定義都以宣告圖表類型開始，接著是圖表及其內容的定義。此宣告會通知解析器程式碼應該產生哪種類型的圖表。

範例：下面的程式碼適用於實體關係圖，由 erDiagram 宣告指定。接下來是其中表示的不同 Entities 的定義。

「開始使用」章節也提供了一些 Mermaid 語法的實際範例。

圖表中斷

應注意某些可能會中斷圖表的單字或符號。這些單字或符號很少，通常只會影響特定類型的圖表。下表將持續更新。

圖表中斷器	原因	解決方案
註解
%%{``}%%	類似於指令，會混淆渲染器。	在使用 %% 的註解中，請避免使用「{}」。
流程圖
'end'	「End」這個字會導致流程圖和循序圖中斷	將它們包在引號中，以防止中斷。
節點內的節點	Mermaid 對於巢狀圖形會感到困惑	將它們包在引號中，以防止中斷

Mermaid 線上編輯器

現在，您已經了解不應在圖表中加入哪些內容，您可以在Mermaid 線上編輯器中嘗試看看。

設定

設定是 Mermaid 的第三部分，在部署和語法之後。它處理 Mermaid 在不同部署中自訂的不同方式。

如果您有興趣修改和自訂 Mermaid 圖表，您可以在這裡找到設定可用的方法和值。它包括主題。本節將介紹設定 Mermaid 圖表行為和外觀的不同方法。以下是最常用的方法，它們都與 Mermaid 的部署方法相關聯。

線上編輯器中的設定區段。

您可以在此處編輯某些值，以變更圖表的行為和外觀。

initialize() 呼叫

當 Mermaid 透過 API 或透過 <script> 標籤呼叫時使用。

指令

允許在圖表呈現之前對其進行有限的重新設定。它可以變更圖表的字型樣式、顏色和其他美觀方面。您可以在定義中加入指令 %%{ }%%。它可以在圖表定義之上或之下完成。

主題操作

使用指令變更主題的應用。Theme 是 Mermaid 設定中的一個值，它決定圖表的色彩配置。

版面配置和外觀

我們已重新調整 Mermaid 呈現圖表的方式，以便啟用選擇版面配置和外觀等新功能。目前，這項功能支援流程圖和狀態圖，並計畫將支援範圍擴展到所有圖表類型。

選取圖表外觀

Mermaid 為您的圖表提供各種樣式或「外觀」，讓您可以自訂視覺外觀以符合您的特定需求或偏好。無論您偏好手繪還是經典樣式，您都可以輕鬆自訂圖表。

可用的外觀

• 手繪外觀：若要獲得更個人化、更有創意的風格，手繪外觀可為您的圖表帶來類似草圖的品質。這種樣式非常適合非正式場合，或者當您想要為圖表增添一點個人風格時。
• 經典外觀：如果您偏好傳統的 Mermaid 樣式，經典外觀會保留許多使用者熟悉的原貌。它非常適合跨專案保持一致性，或者當您想要保持熟悉的美感時。

如何選取外觀

您可以透過在 Mermaid 圖表程式碼的中繼資料區段中新增 look 參數來選取外觀。以下為範例

選取版面配置演算法

除了自訂圖表的外觀之外，Mermaid Chart 現在還允許您選擇不同的版面配置演算法，以更好地組織和呈現您的圖表，特別是當處理更複雜的結構時。版面配置演算法決定節點和邊緣在頁面上的排列方式。

支援的版面配置演算法：

• Dagre（預設）：這是 Mermaid 長期以來使用的經典版面配置演算法。它在簡單性和視覺清晰度之間取得了很好的平衡，使其成為大多數圖表的理想選擇。
• ELK：對於那些需要更複雜的版面配置功能的人來說，特別是當處理大型或複雜圖表時，ELK (Eclipse Layout Kernel) 版面配置提供進階選項。它提供更優化的排列，可能會減少重疊並提高可讀性。這不包含在開箱即用的功能中，而是需要在整合 Mermaid 時新增，以供想要支援 ELK 的網站/應用程式使用。

如何選取版面配置演算法：

您可以直接在 Mermaid 圖表程式碼的中繼資料區段中指定版面配置演算法。以下為範例

在此範例中，layout: elk 行將圖表設定為使用 ELK 版面配置演算法，以及手繪外觀和森林主題。

自訂 ELK 版面配置：

使用 ELK 版面配置時，您可以進一步調整圖表的設定，例如節點的放置方式以及是否應合併平行邊緣

• 若要合併平行邊緣，請使用 mergeEdges: true | false。
• 若要設定節點放置，請使用 nodePlacementStrategy 以及下列選項
  • SIMPLE
  • NETWORK_SIMPLEX
  • LINEAR_SEGMENTS
  • BRANDES_KOEPF（預設）

範例設定

---
config:
  layout: elk
  elk:
    mergeEdges: true
    nodePlacementStrategy: LINEAR_SEGMENTS
---
flowchart LR
  A[Start] --> B{Choose Path}
  B -->|Option 1| C[Path 1]
  B -->|Option 2| D[Path 2]

#### Using Dagre Layout with Classic Look:

另一個範例

---
config:
  layout: dagre
  look: classic
  theme: default
---

flowchart LR
A[Start] --> B{Choose Path}
B -->|Option 1| C[Path 1]
B -->|Option 2| D[Path 2]

這些選項讓您可以彈性建立不僅外觀精美，而且還能以最適合您的資料結構和流程的方式排列的圖表。

整合 Mermaid 時，您可以在初始化呼叫中加入外觀和版面配置的設定。這也是您加入載入 elk 的地方。