技術圖表通常會變得過時,因為編輯它們需要找到原始設計檔案、開啟單獨的應用程式並匯出另一個影像。Mermaid 採用不同的方法:圖表被定義為文本並存儲在文件旁邊。
要將 Mermaid 新增到 Markdown,請將圖表定義放在圍欄程式碼塊內,並使用 mermaid 語言識別符號。使用 Mermaid 圖表預覽 在本地呈現語法、更正錯誤、複製完整的 Markdown 柵欄或下載 SVG。
本指南從一個小流程圖開始,然後構建序列、類、甘特圖、思維導圖和實體關係圖。
Mermaid 30 秒內
基本的 Mermaid 塊如下所示:
```mermaid
flowchart LR
Draft --> Review
Review --> Publish
```
開放柵欄告訴相容的渲染器內容是 Mermaid 語法。 flowchart LR 選擇從左到右排列的流程圖。其餘的線定義節點和連線。
如果目標不支援Mermaid,讀者通常會看到程式碼塊而不是圖表。該後備保留了原始碼,但它並不能替代釋出前檢查相容性的方法。
為什麼使用基於文本的圖表?
Mermaid 當圖表滿足以下條件時特別有用:
- 屬於版本控制文件;
- 隨程式碼或程式一起更改;
- 需要有意義的拉取請求差異;
- 使用標準形狀和關係;
- 應該可以在沒有專有設計檔案的情況下進行編輯;
- 必須在淺色和深色主題中重新生成。
它不太適合詳細插圖、畫素完美佈局、徒手註釋或需要精確手動放置的視覺設計。在這些情況下,請使用繪圖工具並匯出可訪問的 SVG 或影像。
示例 1:流程圖
流程圖描述過程、決策或路由規則。
```mermaid
flowchart TD
A[Choose a DOCX file] --> B{File valid?}
B -->|Yes| C[Convert to Markdown]
B -->|No| D[Show an error]
C --> E[Review the output]
E --> F[Copy or download]
```
關鍵語法:
TD表示從上到下。LR表示從左到右。[Text]建立一個矩形流程節點。{Text}建立一個決策節點。-->建立定向連線。-->|Label|將文本新增到連線。
使用穩定、短的節點 ID,例如 A or validate。將可見標籤保留在括號內,以便更改措辭不需要更改每個連線。
新增子圖
子圖組相關步驟:
```mermaid
flowchart LR
subgraph Browser
Upload[Choose file] --> Convert[Convert locally]
end
subgraph Output
Preview[Preview Markdown] --> Save[Download file]
end
Convert --> Preview
```
當分組傳達所有權、系統邊界或階段時使用子圖。不要僅僅為了裝飾而新增盒子。
示例 2:序列圖
序列圖按時間順序顯示互動。它們非常適合“API”呼叫、身份驗證、瀏覽器工作流程和事件驅動系統。
```mermaid
sequenceDiagram
autonumber
actor User
participant Browser
participant Converter
User->>Browser: Select DOCX file
Browser->>Converter: Pass local file data
Converter-->>Browser: Return Markdown
Browser-->>User: Show editable preview
```
常用箭頭:
->>傳達了明確的資訊。-->>傳送虛線響應。participant宣告系統或服務。actor聲明瞭人類或外部角色。autonumber按順序標記互動。
專注於一種場景。試圖顯示每個替代方案和每個內部函式的序列圖變得比程式碼更難理解。
顯示替代路徑
```mermaid
sequenceDiagram
participant Client
participant API
Client->>API: POST /documents
alt Valid request
API-->>Client: 201 Created
else Invalid request
API-->>Client: 400 Bad Request
end
```
使用 alt, else,以及 end 用於有意義的分支。如果該分支需要幾頁解釋,請連結到圖表下方的散文。
示例 3:類圖
類圖描述型別、屬性、操作、繼承和關係。
```mermaid
classDiagram
class Document {
+String name
+String content
+convert()
}
class MarkdownDocument {
+String frontmatter
+render()
}
Document <|-- MarkdownDocument
```
此示例指出 MarkdownDocument 繼承自 Document。使用類圖作為概念模型,而不是自動替換完整的“API”參考文件。
好的類圖會省略那些無助於讀者理解設計的細節。顯示每個私有欄位可以將圖表變成原始碼的不易搜尋的版本。
示例 4:甘特圖
甘特圖顯示隨時間變化的任務。它們對於釋出計劃、遷移和文件專案非常有用。
```mermaid
gantt
title Documentation migration
dateFormat YYYY-MM-DD
section Preparation
Inventory content :done, inventory, 2026-11-03, 3d
Define templates :done, templates, after inventory, 2d
section Migration
Convert documents :active, convert, 2026-11-08, 7d
Editorial review :review, after convert, 5d
section Publish
Final validation :validate, after review, 2d
```
保持日期明確,並在一項任務依賴於另一項任務時使用任務 ID。請記住,當實際專案進度發生變化時,儲存在文件中的圖表不會自行更新。分配所有權以使其保持最新狀態。
示例 5:思維導圖
思維導圖圍繞中心主題組織想法。
```mermaid
mindmap
root((Markdown quality))
Structure
Headings
Lists
Tables
Accessibility
Alt text
Link text
Reading order
Publishing
GitHub
Obsidian
Documentation site
```
思維導圖在規劃或作為高階概述時最有效。它們對於精確關係不太有用,因為樹結構可能暗示真實概念重疊的層次結構。
示例 6:實體關係圖
ER 圖描述資料實體及其關係。
```mermaid
erDiagram
AUTHOR ||--o{ DOCUMENT : writes
DOCUMENT ||--o{ REVISION : contains
DOCUMENT }o--o{ TAG : uses
AUTHOR {
string id
string name
}
DOCUMENT {
string id
string title
datetime published_at
}
```
使用 ER 圖來解釋模型,並使用模式或遷移檔案來定義實現。圖表可能會省略與當前解釋無關的索引、約束和欄位。
釋出前預覽Mermaid
直接在長的“Markdown”文件中編寫圖表會使語法錯誤難以隔離。集中預覽迴圈速度更快:
- 開啟 Mermaid 圖表預覽.
- 僅貼上圖表定義,不貼上外部程式碼欄。
- 渲染圖表。
- 讀取任何語法錯誤並更正引用的區域。
- 複製生成的圍欄Markdown。
- 當目標需要靜態資源時下載 SVG。
- 在真實平臺上測試最終的Markdown。
預覽以嚴格的安全配置在瀏覽器中呈現。即使另一個“Mermaid”安裝允許,圖表回撥和其他互動行為也可能被停用。這種保守的行為適合通用預覽工具。
常見 Mermaid 錯誤
圖表型別丟失
錯誤:
A --> B
正確:
flowchart LR
A --> B
第一行標識圖語法。
標籤中的標點符號會破壞解析
引用複雜標籤:
flowchart LR
A["Parse input: DOCX, HTML, or text"] --> B["Create Markdown"]
這對於類似於語法的括號、標點符號和標籤特別有用。
保留的 Word 被意外使用
Mermaid語法有關鍵字。官方流程圖文件特別警告小寫 end 可能會破壞流程圖。將其大寫或將可見文本放置在帶引號的節點標籤內:
flowchart LR
Start --> Finish["End"]
程式碼圍欄不正確
語言識別符號緊接在左反引號之後:
```mermaid
flowchart LR
A --> B
```
不要縮排整個柵欄,除非周圍的 Markdown 語法需要它。
它可以在一個平臺上執行,但不能在另一個平臺上執行
Mermaid 不斷發展,平臺可以使用不同的渲染器、版本、安全設定和啟用的圖表型別。最新“Mermaid”版本支援的語法功能在使用其他實現或舊版本的平臺中可能會失敗。
對於在平臺之間移動的文件,首選廣泛支援的語法。在每個所需的目的地測試高階形狀、主題、指令和更新的圖表型別。
平臺相容性
相容性應該被測試而不是假設:
| 平臺 | 當前記錄的方法 | 重要提示 |
|---|---|---|
| GitHub | 使用圍欄 mermaid block | GitHub Markdown 檔案、問題、討論、拉取請求和 wiki 中的文件呈現 |
| GitLab | 在 GitLab Flavored Markdown 中使用 Mermaid 程式碼塊 | GitLab 記錄了其支援的 Mermaid 版本;自我管理安裝可能有所不同 |
| Obsidian | 使用圍欄 mermaid 註釋中的塊 | Obsidian 的渲染器和支援的功能可能會在版本之間發生變化 |
| MkDocs 材料 | 配置Mermaid 自定義圍欄 | 本機主題整合需要記錄 pymdownx.superfences configuration |
| 通用Markdown解析器 | 通常僅顯示程式碼 | Mermaid 渲染通常需要 JavaScript 整合或構建外掛 |
在依賴新功能之前檢查當前的官方文件:
對於您控制的文件站點,固定 Mermaid 依賴項版本並測試升級。否則,微小的語法更改可能會改變整個站點的圖表。
Mermaid 和輔助功能
渲染的 SVG 不會自動向每個讀者傳達其含義。將圖表視為視覺摘要,並在附近的散文中提供等效的解釋。
對於之前的轉換流程圖,新增文本,例如:
使用者選擇“DOCX”檔案。有效檔案在本地轉換並顯示以供稽核;無效檔案會產生錯誤。然後,使用者可以複製或下載已審閱的“Markdown”。
無障礙實踐:
- 介紹圖表解釋的內容;
- 在複雜的圖表後總結結論;
- 不要僅用顏色來編碼含義;
- 使用可讀標籤而不是內部縮寫;
- 在明暗主題中保持足夠的對比度;
- 避免需要精確滑鼠互動的圖表;
- 提供基本資訊的文本或表格替代方案;
- 匯出 SVG 時請小心。
原始碼對作者有用,但對讀者來說不一定是一個好的文本替代品。
設計保持可讀性的圖表
每個圖表保留一個目的
圖表應該回答諸如“請求失敗後會發生什麼?”之類的問題。或“哪個服務擁有每個資料儲存?”如果它試圖解釋整個系統,請將其拆分。
喜歡短標籤
用散文寫出詳細的解釋。長標籤會導致節點變窄、換行笨拙以及移動螢幕上的圖表變大。
有意使用方向
從左到右的流程非常適合短流程和請求路徑。自上而下的流程通常更適合窄螢幕。在提交之前預覽兩者。
限制視覺樣式
自定義顏色可能與深色模式或平臺主題衝突。從渲染器的預設值開始。僅當樣式傳達含義並在所有必需的主題中保持可讀時才新增樣式。
將來源放在其解釋附近
如果可能,將 Mermaid 塊儲存在同一個 Markdown 檔案中。這使得散文和圖表在一篇評論中一起改變。
Mermaid 與靜態影像
在以下情況下選擇Mermaid:
- 圖表經常變化;
- 原始碼差異很有價值;
- 佈局使用標準圖表型別;
- 釋出平臺可靠地呈現Mermaid。
在以下情況下選擇 SVG 或 PNG:
- 設計需要精確的手工佈局;
- 目的地不渲染Mermaid;
- 確切的外觀必須保持固定;
- 外部共享需要獨立資產。
一種有用的混合方式是維護“Mermaid”源並將 SVG 匯出到無法渲染它的目標。將原始檔放在匯出的資源旁邊並記錄如何重新生成它。
使用 Markdown 轉圖片 用於共享渲染的 Markdown 內容,或直接從 Mermaid 圖表預覽 當圖表本身就是資產時。
FAQ
Mermaid 是標準 Markdown 的一部分嗎?
A 號圍欄 mermaid 塊是相容應用程式和構建系統識別的擴充套件。基本的“Markdown”解析器可以將其呈現為普通程式碼。
GitHub 是否渲染 Mermaid 圖表?
是的。GitHub 的文件描述了 Markdown 檔案和多個協作介面中的 Mermaid 渲染。測試較新的語法,因為 GitHub 控制已部署的渲染器和安全設定。
我可以在 Obsidian 中使用 Mermaid 嗎?
Obsidian官方幫助文件Mermaid註釋中的柵欄式圖塊。功能支援可能會隨著應用程式的渲染器而變化,因此請在安裝的版本中驗證複雜或新引入的圖表型別。
Mermaid 能否取代架構文件?
不。圖是系統的一個檢視。將其與決策、所有權、約束、故障行為以及權威介面或模式的連結配對。
為什麼我的圖表在深色模式下呈現不同?
平臺可以應用不同的 Mermaid 主題、CSS 變數、字型和背景。在測試完這兩個主題之前,請避免硬編碼顏色。
我應該提交匯出的 SVG 檔案嗎?
當釋出目標需要靜態資源或渲染結果必須保持穩定時提交 SVG。還要保留“Mermaid”源和記錄的重新生成過程,以防止兩個版本發生漂移。
Mermaid 對於機密圖表安全嗎?
保密性取決於編輯和出版工作流程。WordToMD 的預覽會在瀏覽器中呈現圖表,但將 Markdown 或 SVG 釋出到儲存庫或站點則遵循該目標的訪問控制。
結論
Mermaid 使圖表易於維護,因為原始碼與 Markdown 一起存在。從一個小的圍欄塊開始,選擇與問題匹配的圖表型別,預覽語法,並在最終的渲染器中測試它。當目的地需要靜態資產時,使用散文來解釋基本含義並匯出 SVG。
嘗試中的示例 Mermaid 圖表預覽,編輯周圍的文件 Markdown 編輯,並保持圖表足夠集中,以便未來的貢獻者可以理解並更新它,而無需重新繪製整個頁面。