流程圖

flowchart LR
  A([Start]) --> B{OK?}
  B -->|yes| C[(Database)]
  B -- no --> D[/Input/]:::warn
  C & D ==> E(((End)))
  subgraph grp [Retry]
    direction TB
    F --> G
  end
  E -.-> grp
  classDef warn fill:#fde68a,color:#92400e

timeline:
  enter C slide-right, enter B-C fade
  enter D slide-bottom, enter B-D fade, highlight D glow
  enter subgraph:1 fade, enter E-grp fade

標頭與方向

flowchart 和 graph 意思相同,後面一定要接方向:

方向 意思
TB、TD 由上而下
BT 由下而上
LR 由左而右
RL 由右而左

方向要大寫,標頭後面不能接分號。只在 subgraph 裡可以用 direction 另外指定方向:寫在 subgraph 外面的 direction LR 不會有作用,整張圖維持標頭的方向,並發出警告。

註解

  • 一行開頭(忽略前面的空白)是 %% 的才是註解。寫在一行中間的 %% 不是註解:在節點標籤、連線標籤、subgraph 標題或 click 提示文字裡會當成文字保留(A[50 %% done] 畫出「50 %% done」);接在完整敘述後面(A --> B %% note)則會報錯,提示把註解移到獨立的一行。
  • 整行只有 %% 也會報錯;請寫成 %% 文字,或留空行。
  • 在 timeline: 區塊裡,%% 寫在一行的任何位置都是註解。

節點

節點 id 由英數字、_、. 和 - 組成(例如 step1、api.v2、a-b);- 後面不能接 >、- 或 .,因為那會變成箭頭的開頭。只寫 id 的話,會畫成以 id 為標籤的矩形。

id 不能是 end、style、class、subgraph、graph 這類關鍵字,也不能以關鍵字開頭再接標點(end-x、style.x、A --> end 都會報錯,錯誤訊息會建議 endX 這樣的名字)。只是包含這個字的 id(endX、end_x、A-end)沒有問題。

語法 形狀
A[文字] 矩形
A(文字) 圓角矩形
A([文字]) 體育場形
A[[文字]] 子程序
A[(文字)] 圓柱(資料庫)
A((文字)) 圓形
A(((文字))) 雙圓
A>文字] 旗形
A{文字} 菱形(判斷)
A{{文字}} 六角形
A[/文字/] 平行四邊形
A[\文字\] 反向平行四邊形
A[/文字\] 梯形
A[\文字/] 倒梯形

形狀資料區塊

flowchart LR
  A@{ shape: cloud, label: "網際網路" } --> B@{ shape: doc, label: "報表" }
  C[佇列]@{ shape: h-cyl }
  D@{
    shape: person
    label: "讀者"
  }
  • A@{ … } 用 YAML 指定節點的形狀和文字:寫在一行是 flow mapping,跨行就是 block YAML(引號字串裡的換行會畫成 <br/>)。可以寫在節點自己的一行、連線的任一端、括號或 :::名稱 之後(A[x]:::c@{ shape: circle }),也可以加在前面已經寫過的節點上,原本的文字會保留。@ 前面不能有空白,} 後面不能有東西,一個節點只能有一個區塊;寫在 subgraph 的 id 上會報錯。
  • shape: 指定形狀。上面表格的十四種括號形狀都可以用名字指定:rect、rounded、stadium、fr-rect、cyl、circle、dbl-circ、odd、diam、hex、lean-r、lean-l、trap-b、trap-t,以及它們的別名,例如 db、decision、subroutine。其餘的列在下面的表格。不是形狀的名字(foo、Rect)會報錯;Siren 不認得的 key 會略過並發出警告。
  • label: 指定文字,會當成 Markdown 字串讀,除非 labelType 是 text 或 string。
  • icon: "prefix:name" 從嵌入頁面註冊的圖示包畫出圖示,48px 見方或 h 像素,form 可以是 square、rounded 或 circle,標籤在圖示下方,pos: t 改成上方。Playground 沒有註冊任何圖示包,所以在 Playground 裡圖示節點會報錯。
  • img: "data:image/…" 以原始大小畫出圖片,或用 w、h 指定(constraint: on 維持比例),標籤在下方,pos: t 改成上方。只畫 data URL;其他網址的圖片會報錯,提示把圖片嵌進文件。支援 PNG、GIF、JPEG、WebP 和 SVG,4 MB 以內。
形狀 名稱
缺角矩形(卡片) notch-rect、card、notched-rectangle
缺角五邊形(迴圈上限) notch-pent、loop-limit、notched-pentagon
斜邊矩形(手動輸入) sl-rect、manual-input、sloped-rectangle
三角形 tri、extract、triangle
倒三角形(手動檔案) flip-tri、manual-file、flipped-triangle
資料夾 folder、directory
帶線矩形 lin-rect、lined-rectangle、lined-process、lin-proc、shaded-process
分隔矩形 div-rect、div-proc、divided-rectangle、divided-process
窗格(內部儲存) win-pane、internal-storage、window-pane
堆疊矩形 st-rect、procs、processes、stacked-rectangle
標記矩形 tag-rect、tagged-rectangle、tag-proc、tagged-process
沒有外框的文字 text
資料儲存 datastore、data-store
半圓角矩形(延遲) delay、half-rounded-rectangle
弧形梯形(顯示) curv-trap、curved-trapezoid、display
橫放圓柱 h-cyl、das、horizontal-cylinder
帶線圓柱(磁碟) lin-cyl、disk、lined-cylinder
領結形矩形(儲存的資料) bow-rect、stored-data、bow-tie-rectangle
文件 doc、document
帶線文件 lin-doc、lined-document
標記文件 tag-doc、tagged-document
堆疊文件 docs、documents、st-doc、stacked-document
紙帶 flag、paper-tape
大括號,左、右或兩邊 brace(comment、brace-l)、brace-r、braces
水桶 bucket
人形 person
終端機(有 >_ 提示符的視窗) console
瀏覽器(有工具列和網址列的視窗) browser
雲 cloud
爆炸形 bang
分叉橫條 fork、join
沙漏 hourglass、collate
閃電 bolt、com-link、lightning-bolt
小圓 sm-circ、start、small-circle
框線圓 fr-circ、stop、framed-circle
實心圓 f-circ、junction、filled-circle
打叉圓 cross-circ、summary、crossed-circle

最後七種是固定大小、沒有文字的形狀:替它們寫標籤(括號裡或 label:)會報錯。對小圓用 style 或樣式類別也會報錯,因為不會有任何改變。

標籤

  • 標籤可以用中文。
  • 標籤裡要放括號、|、;、& 或箭頭時,用雙引號包起來:A["a (b) | c"]。引號本身不會畫出來。標籤裡的 %% 是文字。
  • 未加引號的標籤不能包含不屬於形狀本身的括號:A[a]b]、A[a}b]、A{a]b},以及沒有配對的 ( 或 )(A[a)b])都會報錯,提示把標籤加上引號。成對的小括號會照樣畫出來(A[f(x)])。
  • Markdown 字串:A["`**粗體** 和 *斜體*`"]。反引號裡可以直接換行,換行會照樣畫出來。這個寫法只適用於節點標籤。
  • <br> 寫在哪裡就在哪裡換行:A["第一行<br>第二行"]。換行之後還是太長的那一行,會再自己換行。
  • 太長的標籤會自己換行,和 Mermaid 一樣:文字寬度超過 175px 就會拆成好幾行,英文在空白處拆、中文在任兩個字之間拆,節點變高而不是變寬。,、) 這類收尾標點不會出現在行首;單一個太長的單字不會被拆開。subgraph 的標題不會換行。
flowchart LR
  A["第一行<br>第二行"] --> B[這個標籤長到放不進一行,會自己換到第二行]
  • 同一個節點宣告兩次、標籤不同時,保留第一次的標籤並發出警告。只寫 id 也算一次宣告:先寫 A --> B、之後才寫 B[End] 的話,標籤會是 B。請在第一次提到節點時就寫上標籤。

連線

箭頭由三個部分組成:線、兩端的端點、長度。

線 寫法
實線 -->、---
粗線 ==>、===
虛線 -.->、-.-
端點 寫法
箭頭 -->、雙向 <-->
圓點 --o、雙向 o--o
叉叉 --x、雙向 x--x
無 ---

端點可以和三種線任意組合,例如 ==o、<-.->。雙向時兩端必須一樣,o--x 和 <-.- 會被拒絕(Mermaid 會默默畫錯,Siren 選擇明確報錯)。箭頭會停在節點的輪廓上:連到菱形、圓形或斜邊形狀時,碰到的是斜邊或弧線本身,而不是外面那個方框。

  • 長度:多加幾個字元可以把線拉長,例如 ---->、-...->、====>。
  • 標籤:A -->|文字| B 或 A -- 文字 --> B(粗線 == 文字 ==>、虛線 -. 文字 .->)。兩種寫法不能同時用在一條線上,標籤也不能是空的。連線標籤畫在線上,底下墊一塊主題 --siren-edge-label-fill 的底色;寬度超過 150px 會自己換行,規則和節點標籤相同,<br> 在這裡也能換行。|文字| 這種寫法裡,未加引號的括號(A -->|a{b| B)、第一個字含有 @,或引號不在開頭,都會報錯:把整個標籤加上引號(A -->|"a{b"| B)。另一種寫法會照字面畫出來(A -- a{b --> B)。
  • 隱形的邊:A ~~~ B 和一般的邊一樣會把 A 和 B 隔開,但不畫線。每多一個 ~,B 就再往後推一層。它也算進 linkStyle 的編號,linkStyle N stroke-width:4px 會讓它現形;寫在上面的標籤會畫出來。
  • 串接:A --> B --> C 會產生兩條邊。
  • 多對多:A & B --> C & D 會產生 A-C、A-D、B-C、B-D 四條邊。& 兩邊都要有空白:A&B 是一個叫 A&B 的節點,A &B 或 A[x]&B 會報錯。沒有箭頭的 A & B 會宣告兩個節點。
  • 自己連自己:A --> A。
  • 分號:A --> B; B --> C 可以把多個敘述寫在同一行。

邊的 id 與邊的資料

flowchart LR
  A e1@--> B e2@-->|重試| C
  e1@{ animate: true }
  e2@{ animation: slow, curve: step }
  classDef hot stroke:#dc2626
  class e2 hot
  • A e1@--> B 把這條邊的 id 設成 e1,timeline 和 class 用它取代 A-B。兩種標籤寫法都能用,串接的每一段也都能有自己的 id。不能用在 A & B --> C 這種群組的邊上,不能和節點或其他邊的 id 重複(包含自動產生的 A-B),不能以關鍵字開頭,也不能是 subgraph 的名字。
  • 寫在邊下面一行的 e1@{ … } 是這條邊的資料。animate: true 或 animation: fast 讓線的虛線以 20 秒一輪流動,animation: slow 是 50 秒一輪;流動和 timeline 自己的效果同時進行,讀者設定減少動態效果時會停止。curve: step 指定曲線,效果和 linkStyle … interpolate 相同,兩者都寫時以後寫的為準。其他 key 會略過並發出警告;fast、slow 以外的 animation,或 Siren 還不會畫的曲線,會報錯。區塊寫在邊的上面會變成宣告一個叫 e1 的節點,因此報錯。
  • class e1 名稱 把樣式類別套到這條邊:宣告套在線上,color 套在標籤上,但指到這條邊的 linkStyle 優先。style e1 … 和 click e1 … 會報錯;邊的樣式請用 linkStyle。

Subgraph

flowchart TB
  subgraph ingest [Ingest]
    direction LR
    Fetch --> Parse
  end
  subgraph store [Store]
    Save
  end
  ingest --> store
  • 開頭有幾種寫法:subgraph ingest(id 和標題都是 ingest)、subgraph ingest [Ingest pipeline](有 id 也有標題)、subgraph "Ingest pipeline"(只有標題,其他地方無法用 id 指到它),以及不加引號的多個字 subgraph Ingest pipeline,同樣只有標題。只有一個字的引號標題(subgraph "t")同時也是 id,subgraph "t" [Ingest] 則是 id t 加上標題。
  • 不加引號的標題不能含有 ,、(、[、{、|、<、=、~、@、-- 或 :::,請改用引號。括號標題後面再接文字(subgraph s1 [t] zz)、最後一個字是 end 的標題,都會報錯;在 subgraph 的 id 上寫 @{ … } 區塊也會報錯。
  • 用 end 結束,可以巢狀。
  • 裡面可以用 direction 另外指定方向,只影響這一層;方向後面多出來的文字(direction LR zz)會略過並發出警告。但只要有一條連線兩端的父層不同、又穿過這個 subgraph,它就會放棄自己的方向:一端在裡面(不管多深)、一端在外面就算,兩端都是它自己的成員但巢狀深度不同也算。這樣的連線會讓從兩端往上、直到兩端最近的共同 subgraph(含)的每一層都放棄方向,改用外層 subgraph 的方向(找最近一層還保有自己方向的),都沒有就用整張圖的,和 Mermaid 12 相同。沒寫 direction 的 subgraph 也一樣,跟著外層 subgraph 的方向排。並排的兩個 subgraph 或節點之間的連線(ingest --> store)兩邊都不受影響;成員連到自己所屬 subgraph 的連線則算。
  • 有一種圖排不出來,會報錯並點名相關的元素:在一個保有自己 direction 的 subgraph 裡,巢狀的 subgraph 和它自己的成員之間有連線(B --> F,F 在 B 裡面,兩者都在設了 direction LR 的 A 裡面)。請拿掉外層的方向,或讓巢狀的那個連到它外面的東西。
  • 同一層的 subgraph 後結束(end)的排前面,而且所有 subgraph 都排在外面的節點前面,和 Mermaid 相同:先寫 subgraph SA … end、再寫 subgraph SB … end、最後 X,從左到右會是 SB、SA、X。
  • 可以直接用 subgraph 的 id 連線(ingest --> store),subgraph 寫在連線下面也可以。
  • 一個節點只屬於第一個提到它的 subgraph。

樣式

flowchart LR
  A:::hot --> B --> C
  style B fill:#e0f2fe,stroke:#0284c7
  classDef hot fill:#fee2e2,stroke:#dc2626,color:#991b1b
  class C hot
  linkStyle 0 stroke:#dc2626
  linkStyle 1 interpolate step
  linkStyle default stroke:#94a3b8
  • style 節點 屬性:值,屬性:值:套用在一個節點,或用 id 套用在一個 subgraph 上(style ingest fill:#f0f9ff,color:#1e3a8a 會填滿外框並改標題的顏色)。同一個名字既是節點又是 subgraph 時,套用在 subgraph 上。這裡不接受邊的 id,請用 linkStyle。
  • classDef 名稱 屬性:值,...:定義樣式類別。名稱可以用英數字和 _、任何文字的字母,以及夾在字中間的 -、.、#、+;不能以數字開頭。classDef a,b ... 會同時定義兩個類別。可以寫在套用它的敘述之前或之後。
  • class A,B 名稱 或 A:::名稱:把樣式類別套用在節點或 subgraph 上;class e1 名稱 則套用在有 id 的邊上。::: 也可以接在有標籤的節點或連線端點上(A[x]:::hot --> B:::cold)。一次只能套一個類別:A:::c,d 會報錯。套用沒有用 classDef 定義的類別會發出警告,目標照原樣畫、不上樣式。
  • classDef default 屬性:值,...:套用到每一個節點,其他類別或 style 都會蓋過它。不會套用到 subgraph。
  • linkStyle 0 ...、linkStyle 0,2 ...、linkStyle default ...:幫邊上樣式。編號依邊的宣告順序從 0 開始算,隱形的 ~~~ 邊也算;default 會套到所有邊,但指定編號的逐屬性優先。
  • linkStyle 1 interpolate step、linkStyle default interpolate linear,或是和樣式寫在同一行的 linkStyle 1 interpolate step stroke:#f00:指定這條邊用哪種曲線畫,和 Mermaid 一樣。預設是 rounded:橫直線段組成的路線加上圓角,和 Mermaid 12 畫的一樣,兩條邊交叉時其中一條會用小弧跳過另一條。其他可選 basis(平滑曲線,不畫跨線小弧)、linear、step、stepBefore、stepAfter。名稱分大小寫,指定編號的曲線優先於 default。Mermaid 有但 Siren 還沒實作的七種(cardinal、bumpX、bumpY、catmullRom、monotoneX、monotoneY、natural)會報錯,這條邊維持原本的曲線;Mermaid 也不認得的名稱會畫成 rounded 並發出警告。
  • color 會套在文字上,其他屬性套在形狀上(邊的 stroke 會同時影響線和箭頭)。
  • 同一個目標上,style 永遠蓋過樣式類別,不管誰先寫,和 Mermaid 相同。兩條 style、或兩個類別套在同一個目標上時,同一個屬性以後寫的為準。
  • timeline 強調某個目標的期間,強調效果的顏色和線寬會取代作者設定的 stroke 和 stroke-width,強調結束後恢復。
  • 指到不存在的節點會直接略過、不報錯,和 Mermaid 相同。
  • 值的寫法和 Mermaid 一樣:顏色寫十六進位色碼或顏色名稱(fill:#ff0000、fill:red),字型用單引號(font-family:'Noto Sans')。rgb(…)、var(--x) 這類 CSS 函式、括號、|、@、{、}、=、~、箭頭或連續兩個 -、雙引號、; 或反斜線都會報錯;值是 rgb(r,g,b) 時,錯誤訊息會告訴你該寫的色碼。值裡有空白沒有問題(stroke-dasharray:5 5)。

互動

flowchart LR
  Docs --> API
  click Docs href "https://example.com/docs" "說明文件" _blank
  click API call openPanel("api")
寫法 效果
click A href "網址" 或 click A "網址" 連結
click A href "網址" "提示" _blank 或 click A "網址" "提示" _blank 滑鼠移上去顯示提示,並在新分頁開啟;也可以用 _self、_top、_parent
click A call fn()、click A call fn("參數") 呼叫 callback
click A fn callback 的簡寫
  • 網址只允許 http:、https:、mailto: 和相對路徑。其他協定(如 javascript:)會被拒絕,那一條互動會被丟掉。
  • callback 會觸發嵌入端提供的 onClick。在 Playground 裡點擊不會有反應。
  • 提示文字在滑鼠移到節點上時顯示。
  • click 只能指到節點:寫邊的 id 會報錯。

無障礙

accTitle: 標題 和 accDescr: 描述 會成為 SVG 的 <title> 和 <desc>,描述也可以用 accDescr { ... } 跨好幾行。冒號前面有空白也可以。重複寫的話以最後一個為準。

Timeline 目標

元素 id 例子
節點 節點 id B
邊 起點-終點,重複的加 #2、#3 A-B、A-B#2
有 id 的邊 寫在箭頭前面的那個 id e1
subgraph subgraph:N,依開啟順序編號,巢狀的也一起算 subgraph:1
  • A --> B --> C 的兩條邊是 A-B 和 B-C。
  • A & B --> C 的兩條邊是 A-C 和 B-C。
  • 重複的次數是把同一對節點之間的每一條邊都算進去,有沒有 id 都算:先寫 A e1@--> B、再寫 A --> B,兩條邊是 e1 和 A-B#2。
  • 連到 subgraph 的邊用原始碼裡寫的名字:ingest --> store 的 id 是 ingest-store。但 subgraph 本身只能用 subgraph:N 指定,名字不行。
  • 節點和邊共用一個 id 時(節點 A-B 旁邊有 A --> B),在 timeline 裡指到它會報錯;請給那條邊自己的 id,或把節點改名。

尚未支援

語法 目前的行為
非 ASCII 的節點 id(節點 --> B) 報錯。中文請放在標籤裡:n1[節點]
在 Playground 裡用 A@{ icon: "fa:user" } 報錯:Playground 沒有註冊圖示包
A@{ img: "https://…" } 報錯,只畫 data: URL
A ~~ B、A ~~~> B 報錯,隱形的邊是沒有端點的 ~~~
標籤裡的 #quot;、fa: 圖示 當成一般文字畫出來
邊標籤、subgraph 標題裡的 Markdown 當成一般文字畫出來