若要在 Mac 版 Obsidian 中建立易讀且風格一致的 Mermaid 流程圖，請在每張圖表內定義可重複使用的節點樣式。保留應用程式主題，確認安裝版本使用的渲染器，只有在需要共用預設值時才加入限定於圖表的 CSS。

本指南會建立一張小型流程圖，包含風格一致的節點填色、易讀標籤，以及一個清楚標示的替代步驟。所有標籤皆為虛構內容。目標是為一般筆記建立可重複使用的樣式模式，並另外說明 Mermaid 與 Obsidian 較新的 Pele 渲染器在行為上的差異。

選擇設定前，先確認已安裝的渲染器

請在 設定 → 關於 → 應用程式 → 目前版本 找到你的版本；這是 Obsidian《Early access versions help》所記載的位置。排查樣式問題前，先記下版本號。

有一個重要的版本界線：2026 年 10 月 22 日發布的 Obsidian 1.15.0 Desktop（標示為 Early access） 發行說明中，首次推出用於渲染 Mermaid 圖表的 Pele。說明指出，Pele 支援 Mermaid 12.1.0 語法、使用佈景主題的色彩與字型，並產生不同的 SVG 類別。這份發行說明描述的是該特定版本，無法據此確認你的 Mac 安裝了哪種渲染器。請參閱 Obsidian 1.15.0 Desktop。

複製其他教學的設定前，請先查看此判斷表：

你的渲染環境 請從此處開始 請留意的限制
Obsidian 使用 Mermaid 本身 流程圖原始碼中的類別；也可使用圖表 frontmatter 設定功能取決於安裝的 Mermaid 版本。
Obsidian 使用 Pele 原始碼中的樣式；也可使用 Pele CSS 變數 Mermaid 佈景主題與 themeVariables 色彩不適用。
取代圖表渲染器的外掛 外掛所記載的渲染器與設定 內建渲染器的行為不足以判定是否相容。

即使 Pele 接受 Mermaid 語法，其版面配置與外觀仍由 Pele 自行定義。Pele 的相容性文件也指出，設定支援會依圖表類型而異。請將語法相容性與視覺輸出是否相同視為兩個不同問題。

在筆記中建立可重複使用的流程圖樣式

建立新筆記，貼上以下完整區塊，包含開頭與結尾的圍欄。Obsidian 的進階格式語法文件指定使用標記為 mermaid 的圍欄程式碼區塊來呈現圖表。

```mermaid
flowchart TD
    A[Item A] --> B[Step B]
    B --> C[Result C]
    B --> D[Option D]

    classDef standard fill:#edf2f7,stroke:#475569,color:#172033,stroke-width:2px;
    classDef alternate fill:#e0f2fe,stroke:#0369a1,color:#172033,stroke-width:2px;
    class A,B,C standard;
    class D alternate;
```

Mermaid 記載的 classDef 語法可定義可重複使用的外觀；class 則會將該樣式套用到指定節點。此處有三個節點共用 standard，另一個節點使用 alternate。請將節點識別碼與顯示標籤分開，方便追蹤文字修改。這些功能詳見 Flowcharts — Basic Syntax。

此配色是示範用的設計選擇，將淺色填滿區搭配深色文字與較醒目的邊框。標籤 Option D 也標明了替代步驟，因此其含義不會只依賴藍色填滿區來傳達。

預覽筆記，並以平常的閱讀大小檢查標籤。預期結果是三個相同樣式的灰色節點與一個藍色節點。先保留渲染器的預設箭頭樣式，這樣一次只調整一項設定，更容易判斷效果。

若要重複使用此模式，請將整個區塊複製到另一篇筆記，修改標籤與連線，並更新最後兩行的節點清單。保留一份配色參考。這是一種手動慣例：修改參考版本不會自動更新其他位置已複製的圖表。

Pele 也支援在圖表中定義樣式，其文件說明，當佈景主題變更時，原始碼定義的色彩會保持固定。如果你想保留 Obsidian 佈景主題，同時維持一致的配色，這種方式便很實用。請參閱 Pele Theming。

只有在 Mermaid 渲染圖表時才使用圖表 frontmatter

如果安裝環境使用 Mermaid 本身且支援圖表 frontmatter，你可以一併設定整張圖表的調色盤與字體。Mermaid 文件指出，從 10.5.0 版起支援 frontmatter 設定。網站層級的初始化由整合應用程式負責；筆記作者則可使用圖表範圍內的設定。請參閱 Mermaid Configuration。

以下完整範例會為三個節點設定共用外觀。請先在獨立的測試區塊中使用：

```mermaid
---
config:
  theme: base
  themeVariables:
    primaryColor: "#edf2f7"
    primaryTextColor: "#172033"
    primaryBorderColor: "#475569"
    lineColor: "#64748b"
    fontFamily: "Arial, sans-serif"
    fontSize: "16px"
---
flowchart TD
    A[Item A] --> B[Step B]
    B --> C[Result C]
```

YAML 必須放在 mermaid 圍欄內，並置於 flowchart TD 前面。這是圖表設定，與 Markdown 檔案頂端的筆記屬性分開。

Mermaid 指定 base 為可自訂的佈景主題，並要求其佈景主題引擎使用十六進位色碼。其佈景主題設定文件列出了上述使用的文字、填滿、邊框、線條與字型變數。這些設定用來描述圖表外觀，不會切換 Obsidian 應用程式的佈景主題。

在 Pele 上修改此範例的 themeVariables 色彩不會得到相同結果：這些色彩明確不受支援。若要固定節點色彩，請使用原始碼定義的類別；若要設定共用的渲染器預設值，請使用下方的 CSS 變數方法。不要因為 Mermaid 佈景主題設定被忽略，就繼續調整十六進位色值。請參閱 Pele Compatibility。

使用小型 CSS 片段設定 Pele 共用預設值

如果安裝環境使用 Pele，CSS 變數是另一種受支援的方法。若多張圖表應共用預設樣式，而且你偏好修改一份樣式表，而非逐一編輯每個區塊，這種方式就很實用。

以下完整片段適用於 Pele 流程圖。它會設定文字、填滿區、邊框與連接線色彩，同時不影響周圍筆記與應用程式主題。選取器與變數詳見 Pele Theming。

.pele-flowchart {
  --pele-bg: #ffffff;
  --pele-fg: #172033;
  --pele-line: #64748b;
  --pele-surface: #edf2f7;
  --pele-surface-alt: #e2e8f0;
  --pele-border: #475569;
}

依照 Obsidian 文件記載的桌面版流程安裝：

  1. 開啟 設定。
  2. 在 外觀 → CSS 片段 下，選取 開啟片段資料夾。
  3. 在該資料夾建立名為 diagram-defaults.css 的純文字檔，並貼上 CSS。
  4. 回到 外觀 → CSS 片段，選取 重新載入片段。
  5. 啟用 diagram-defaults。

這些控制項與已儲存片段的自動套用方式，記載於 CSS snippets — Obsidian Help。在 Mac 上，請確認編輯器儲存的檔名包含 .css 副檔名。

使用前一節的三節點圖表測試共用預設值，並移除圖表 frontmatter。原始碼定義的色彩可能會覆寫渲染器預設值，因此第一個範例明確指定的節點類別不適合用來判斷共用填滿變數是否生效。

此片段刻意採用固定的淺色調色盤。如果你偏好的閱讀設定需要不同配色，請一併調整文字、表面、邊框與線條色彩，再檢視結果。--pele-bg 變數適用於背景元素；它不保證整張圖表後方會出現不透明面板。

請讓此片段僅適用於 Pele。Mermaid 的流程圖文件建議使用 classDef 設定節點樣式，並提醒外部 CSS 可能會被 Mermaid 內部樣式覆蓋。針對一種渲染器的樣式表，不應假設也適用於另一種渲染器。請參閱 Mermaid’s CSS classes guidance。

依照固定順序排查難以閱讀的圖表

如果圖表已成功渲染，但外觀不一致，請依照以下步驟處理。這些步驟能分別檢查語法、樣式範圍與可用空間，無須更改應用程式主題。

  1. 縮小測試範圍。 將筆記中的圖表複製到暫存筆記，並只保留三個簡短標籤。如果這個小範例也失敗，請先檢查語法或渲染器支援，再調整色彩。
  2. 選擇一種樣式設定方法。 單獨測試原始碼類別、Mermaid frontmatter 或 Pele 變數。立刻混用會讓覆寫來源更難判斷。
  3. 檢查搭配色彩。 先確認文字與節點填滿區的對比，再檢查邊框和箭頭與周圍筆記的對比。先修正難以閱讀的色彩搭配，再加入其他重點色。
  4. 檢查閱讀寬度。 在平常使用的窗格寬度下預覽圖表。如果圖表太寬，請縮短標籤或試試直向排列。
  5. 逐步增加複雜度。 分批加入其餘節點、替代樣式與邊緣標籤。保留最近一個清晰易讀的版本以便比較。

檢查方向時，Mermaid 將 TD 定義為由上而下，將 LR 定義為由左至右。請先只修改這個宣告，再考慮重寫圖表。請參閱 Flowchart direction。

請在已安裝的 Obsidian 渲染器中評估最終結果。外部編輯器可以協助檢查語法，但 Pele 文件指出，其節點位置、間距與邊緣路徑都與 Mermaid 不同。原始碼相同，不代表幾何配置也必須一致。

在可重複使用的配色旁保留一張小型參考圖表。確認其標籤、節點與連接線在平常的窗格寬度下都清晰易讀後，再將相同慣例套用到工作筆記。樣式一致性來自可重複使用的樣式與明確的渲染器界線；Obsidian 佈景主題可以維持原樣。

來源