為何您的 GitHub README 圖表看起來像外行（以及讓它們變得專業的 4 個只需 10 分鐘的修復方法）

TL;DR
如果你的 README 圖表看起來像每個其他開源專案的，那是由於它們都使用相同的四個預設值。切換到 theme: 'base' 加上調整四個屬性不到十分鐘就能產生一個看起來有意圖的圖表。這是上週 SVG 渲染深入探討.

搞壞你圖表的四個預設值

淡粉藍色調 — 這個default主題來自2014年Bootstrap時代的情緒板。它表示「我是從文件中複製貼上來的。」
彎曲的邊緣(basis) — 適合有機流動，糟糕適合技術圖表。本應清晰的線條最終變得鬆散。
預設字體 — 因觀者而異。在 GitHub 編輯器預覽中看起來還好，在您的 CI 工件中看起來像 Times New Roman。
硬編碼背景 — 暗色頁面的亮色主題，或反之。圖表變成矩形。

每個問題只需要一個配置變更來修復。

修復 1：切換到基礎主題

%%{init: {'theme':'base'}}%%
flowchart LR
  A --> B --> C

base 是唯一一個主題，可讓 themeVariables 完全控制.

修復 2：設置六個主題變數

%%{init: {
  'theme':'base',
  'themeVariables': {
    'primaryColor': '#1e293b',
    'primaryTextColor': '#f8fafc',
    'primaryBorderColor': '#475569',
    'lineColor': '#94a3b8',
    'fontFamily': 'system-ui, sans-serif',
    'fontSize': '14px'
  }
}}%%

六個變數。這就是你實際上需要的全部客製化表面。Mermaid總共暴露了約五十個，但上面這些涵蓋了圖表視覺身份的90%。除非你有特定的理由，否則忽略其餘的部分。

修復 3：線性邊緣

%%{init: {'flowchart': {'curve': 'linear'}}}%%

對於階層結構，使用 step。對於有機流程，保持basis。對於其他情況，linear。

修復 4：亮度/黑暗適應嵌入

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="./diagrams/auth-flow-dark.svg">
  <img alt="Auth flow" src="./diagrams/auth-flow-light.svg">
</picture>

GitHub READMEs 尊重 prefers-color-scheme。發送兩個 SVG，讓 GitHub 選擇。

一個小但重要的注意事項：這只適用於 預渲染的 SVG。 需要您提交到 repo。在您的 README 中內嵌 mermaid 代码區塊無法使用 <picture> — 它們會由 GitHub 自己的 Mermaid 執行環境在顯示時渲染，沒有基於主題交換的鉤子。如果您想在 README 中獲得適應性圖表，您必須先渲染為 SVG。

將所有四者結合起來

這是端到端的最小化可實現美化 README 圖表：

---
config:
  theme: base
  themeVariables:
    primaryColor: '#1e293b'
    primaryTextColor: '#f8fafc'
    primaryBorderColor: '#475569'
    lineColor: '#94a3b8'
    fontFamily: 'system-ui, sans-serif'
    fontSize: '14px'
  flowchart:
    curve: linear
---
flowchart LR
  A[Client] --> B{Auth?}
  B -->|Yes| C[API]
  B -->|No| D[Login]
  C --> E[(Database)]

前文表單 (---\nconfig:\n ...) 是 Mermaid v11 的偏好語法。較舊的 %%{init: {...}}%% 指令仍然有效，且在大多數部落格中會看到它 — 選擇你的渲染器喜歡的哪一種即可.

當自製停止值得花時間

以上都有效。我已發布這個確切的流程。

但當你擁有超過一打圖表，或者你希望幻灯片、文件和 PR 有不同的樣式時，你就要維護一個配置文件。而且每一個新的倉庫貢獻者都需要了解它。這就是我個人覺得無法再繼續下去的地方。

有三個信號表明是時候從手動調整的主題畢業了：

你正在多個倉庫中複製粘貼相同的 themeVariables區塊。
您希望幻灯片演示文稿的樣式與 README 不同，但圖表來源保持相同。
團隊中非技術人員需要製作圖表，而您不希望教他們 YAML 前置部分。

快速方法：貼上，選擇一個主題，導出

美麗圖表是用於 Mermaid、PlantUML 和 draw.io 的網頁編輯器。貼上您的原始碼，選擇 9 個生產主題，輸出 SVG 或 PNG。無需 themeVariables 來維護。（披露：我參與開發它。）

→ 開啟編輯器

最快的路徑是網頁編輯器：

在左側貼上您的 Mermaid 原始碼。
選擇一個主題 來自九個：classic、modern、atlas、blueprint、memphis、obsidian、slate、brutalist、atelier。每一個都是一種完整的設計語言 — 色彩板、字體排印、邊框風格、節點處理 — 不只是顏色交換.
輸出 SVG (向量圖檔供倉庫使用) 或 PNG (standard / high / max 滑鐵盤品質用於簡報).
分享以獲得可公開連結的URL，當來源編輯時會自動更新 — 將其貼入Notion或Linear即可，無需重新上傳.

相同的渲染器也可作為CLI，如果您想自動化README流程：

# Render once, ship to your repo
npx @beauty-diagram/cli beautify flow.mmd --theme modern --out flow.svg

# Or render light + dark in one go for the <picture> embed
npx @beauty-diagram/cli beautify flow.mmd --theme modern   --out flow-light.svg
npx @beauty-diagram/cli beautify flow.mmd --theme obsidian --out flow-dark.svg

CLI 暴露了相同九個主題 (bd themes 列出它們)。它不暴露每個變量的覆蓋 — 哲學是主題是選擇；你不需要調整一個主題，你選擇不同的主題.

總結

README圖表尷尬問題可在十分鐘內解決。四個修復措施，重述：

theme: 'base' — 唯一接受覆蓋的主題.
六個 themeVariables — primaryColor、primaryTextColor、primaryBorderColor、lineColor、fontFamily、fontSize.
flowchart.curve: linear — 尖銳邊緣，適合技術圖表.
<picture> + prefers-color-scheme — 自適應明亮/黑暗，GitHub原生。

絕大多數專案都還沒有做，因為沒有人告訴他們去哪裡找。現在你知道了.

如果這對你有幫助，請按一個 ❤️ 跟隨 — 我會每週發布有關圖表、文件和開發者人體工學的內容。下週：如何在 Notion 中嵌入 Mermaid 圖表（2026 年的四大有效方法).

你見過最醜的 README 圖表是什麼？你實際上反對過的 PR 中有嗎？在評論中放個連結——我正在收集例子，為未來的文章做準備。

推薦訂閱源

DEV Community