Mermaid 主題與設定

自訂 Mermaid 圖表的配色、主題變數與全域設定選項

Overview##

Mermaid 內建五種主題，也支援透過 themeVariables 完全自訂配色。本篇說明如何選擇主題、自訂變數，以及常用的 Configuration 選項。

Built-in Themes##

Mermaid 提供五種預設主題：

透過 initialize() 設定：

mermaid.initialize({
  theme: 'neutral',
});

themeVariables##

base 主題提供一組可自訂的 CSS 變數，控制圖表的每個視覺元素。

通用變數###

Flowchart 專用變數###

Sequence Diagram 專用變數###

設定範例###

以下是本站使用的綠色主題設定：

mermaid.initialize({
  theme: 'base',
  themeVariables: {
    primaryColor: '#e8f5e9',
    primaryBorderColor: '#388e3c',
    primaryTextColor: '#1b5e20',
    lineColor: '#616161',
    secondaryColor: '#f5f5f5',
    tertiaryColor: '#fafafa',
    fontFamily: 'ui-sans-serif, system-ui, sans-serif',
    fontSize: '14px',
  },
});

效果：

Directive Override##

除了全域設定，你也可以在單張圖表中用 %% directive 覆蓋主題：

Configuration Options##

除了主題，initialize() 還有許多控制行為的選項。

通用設定###

mermaid.initialize({
  startOnLoad: false, // false = manual render
  securityLevel: 'strict', // strict | loose | antiscript | sandbox
  logLevel: 'error', // debug | info | warn | error | fatal
  fontFamily: 'arial',
});

Flowchart 設定###

mermaid.initialize({
  flowchart: {
    htmlLabels: true, // label uses HTML rendering
    curve: 'basis', // edge curve: basis | linear | cardinal
    padding: 15, // node padding
    nodeSpacing: 50, // horizontal spacing
    rankSpacing: 50, // vertical spacing
    useMaxWidth: true, // auto fit container width
  },
});

Sequence Diagram 設定###

mermaid.initialize({
  sequence: {
    diagramMarginX: 50, // diagram horizontal margin
    diagramMarginY: 10, // diagram vertical margin
    actorMargin: 50, // space between actors
    width: 150, // actor box width
    height: 65, // actor box height
    boxMargin: 10, // loop/alt box margin
    showSequenceNumbers: true, // same as autonumber
    useMaxWidth: true,
  },
});

Gantt 設定###

mermaid.initialize({
  gantt: {
    titleTopMargin: 25,
    barHeight: 20,
    barGap: 4,
    topPadding: 50,
    sidePadding: 75,
    numberSectionStyles: 4,
    axisFormat: '%Y-%m-%d',
  },
});

Astro Integration##

本站的 Mermaid 設定在 DocLayout.astro 中：

import mermaid from 'mermaid';

async function initMermaid() {
  mermaid.initialize({
    startOnLoad: false,
    theme: 'base',
    themeVariables: {
      primaryColor: '#e8f5e9',
      primaryBorderColor: '#388e3c',
      primaryTextColor: '#1b5e20',
      lineColor: '#616161',
      secondaryColor: '#f5f5f5',
      tertiaryColor: '#fafafa',
      fontFamily: 'ui-sans-serif, system-ui, sans-serif',
      fontSize: '14px',
    },
  });

  // Convert Shiki code blocks to mermaid divs
  document.querySelectorAll('pre[data-language="mermaid"]').forEach((pre) => {
    const code = pre.querySelector('code');
    if (!code) return;
    const raw = code.innerText;
    const div = document.createElement('div');
    div.className = 'mermaid';
    div.textContent = raw;
    pre.replaceWith(div);
  });

  await mermaid.run({ querySelector: '.mermaid' });
}

initMermaid();
document.addEventListener('astro:page-load', initMermaid);

Summary##

• 使用 base 主題搭配 themeVariables 做完全自訂，避免其他主題的變數互相覆蓋
• primaryColor、primaryBorderColor、lineColor 是影響最大的三個變數
• 單張圖表可以用 %%{init: {...}}%% directive 覆蓋全域設定
• securityLevel 預設 strict 即可；loose、antiscript、sandbox 則依信任程度與互動需求調整
• Flowchart 的 curve 選項影響連線的視覺風格（basis 較圓滑，linear 為直線）
• Sequence diagram 用 actorMargin 和 width 控制排版密度