跳轉至

Diagram 的使用

Zensical 內建使用 Mermaid.js 來繪製各類圖表，所以語法可以參考 Mermaid.js 的教學。底下是一些範例。

zensical.toml 設定檔

要開啟圖表功能，請在 zensical.toml 做如下設定。Zensical 會在頁面出現 mermaid 程式區塊時自動初始化：

[project.markdown_extensions.pymdownx.superfences]
custom_fences = [
  { name = "mermaid", class = "mermaid", format = "pymdownx.superfences.fence_code_format" },
]

原生整合的好處

  • 與 instant navigation 相容，不需額外處理
  • 圖表會跟主題字型、顏色一起走
  • 淺色 / 深色模式都能用

本專案另外在 docs/js/mermaid.mjs 註冊了 ZenUML，屬於進階客製，一般教學只要上面這段設定就夠了。

流程圖（Flowchart）

原始程式

```mermaid
graph TD
    A[開始] --> B{條件判斷}
    B -- 是 --> C[執行動作]
    B -- 否 --> D[結束]
    C --> D
```

輸出結果

graph TD
    A[開始] --> B{條件判斷}
    B -- 是 --> C[執行動作]
    B -- 否 --> D[結束]
    C --> D

序列圖（Sequence Diagram）

原始程式

```mermaid
sequenceDiagram
    participant A as 使用者
    participant B as 伺服器
    A->>B: 發送請求
    B-->>A: 回應結果
```

輸出結果

sequenceDiagram
    participant A as 使用者
    participant B as 伺服器
    A->>B: 發送請求
    B-->>A: 回應結果

甘特圖（Gantt Chart）

原始程式

```mermaid
gantt
    title 專案時程表
    dateFormat  YYYY-MM-DD
    section 設計階段
    設計UI         :done,   des1, 2024-02-01, 2024-02-10
    開發API       :active,  dev1, 2024-02-11, 2024-02-20
    測試          :        test1, 2024-02-21, 2024-02-28
```

輸出結果

gantt
    title 專案時程表
    dateFormat  YYYY-MM-DD
    section 設計階段
    設計UI         :done,   des1, 2024-02-01, 2024-02-10
    開發API       :active,  dev1, 2024-02-11, 2024-02-20
    測試          :        test1, 2024-02-21, 2024-02-28

類別圖（Class Diagram）

原始程式

```mermaid
classDiagram
    class Animal {
        +String name
        +eat()
    }
    class Dog {
        +String breed
        +bark()
    }
    Animal <|-- Dog
```

輸出結果

classDiagram
    class Animal {
        +String name
        +eat()
    }
    class Dog {
        +String breed
        +bark()
    }
    Animal <|-- Dog

ERD（實體關聯圖）

原始程式

```mermaid
erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ ITEM : contains
    CUSTOMER {
        int id
        string name
    }
    ORDER {
        int id
        date order_date
    }
    ITEM {
        int id
        string name
        float price
    }
```

輸出結果

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ ITEM : contains
    CUSTOMER {
        int id
        string name
    }
    ORDER {
        int id
        date order_date
    }
    ITEM {
        int id
        string name
        float price
    }

狀態圖（State Diagram）

原始程式

```mermaid
stateDiagram
    [*] --> 狀態A
    狀態A --> 狀態B : 觸發條件
    狀態B --> [*]
```

輸出結果

stateDiagram
    [*] --> 狀態A
    狀態A --> 狀態B : 觸發條件
    狀態B --> [*]

圓餅圖（Pie Chart）

原始程式

```mermaid
pie
    title 瀏覽器市場佔比
    "Chrome" : 64.5
    "Firefox" : 19.2
    "Edge" : 8.1
    "Safari" : 5.2
```

輸出結果

pie
    title 瀏覽器市場佔比
    "Chrome" : 64.5
    "Firefox" : 19.2
    "Edge" : 8.1
    "Safari" : 5.2

Git 分支圖（Git Graph）

原始程式

```mermaid
gitGraph
    commit
    commit
    branch feature
    checkout feature
    commit
    checkout main
    merge feature
```

輸出結果

gitGraph
    commit
    commit
    branch feature
    checkout feature
    commit
    checkout main
    merge feature

Note

Zensical 官方正式支援流程圖、序列圖、狀態圖、類別圖、ER 圖。圓餅圖、甘特圖、Git Graph 等仍可使用，但在手機上的呈現不一定理想。 其他圖種請見 Mermaid.js 官方文件。

總結

步驟 說明
啟用 Mermaid 圖表 在 zensical.toml 設定 pymdownx.superfences.custom_fences
新增 Mermaid 代碼塊 使用 ```mermaid 語法在 Markdown 內寫圖表
啟動預覽 zensical serve
官方支援的圖表 流程圖、時序圖、狀態圖、類別圖、ER 圖

這樣就能輕鬆在 Zensical 中使用 Mermaid.js 繪製圖表！

參考資料