راهنمای نحو mermaid

کوتاه‌ترین نموداری که کار می‌کند

یک فلوچارت به یک خط تعریف و یک پیکان نیاز دارد. TD یعنی از بالا به پایین؛ برای فرایندهای عریض که بهتر جواب می‌دهند از LR استفاده کنید.

flowchart TD
  A[Start] --> B{Ready?}
  B -->|Yes| C[Ship it]
  B -->|No| A

A، B و C شناسه گره هستند — نام‌های داخلی که هرگز کشیده نمی‌شوند. متن داخل کروشه برچسب است و سبک کروشه همان چیزی است که شکل را انتخاب می‌کند.

شکل‌های گره

شکل با جفت جداکننده اطراف برچسب انتخاب می‌شود. این‌ها ارزش به‌خاطر سپردن دارند:

💡وقتی برچسب شامل کروشه، دونقطه یا نقل‌قول است آن را داخل نقل‌قول بگذارید: A["Load (raw) data"]. بدون نقل‌قول، تجزیه‌کننده علائم نگارشی شما را به‌عنوان نحو می‌بیند.

پیکان‌ها

طول پیکان هم معنادار است: --> یک رتبه است، ---> مقصد را یک رتبه پایین‌تر می‌برد. این ساده‌ترین کنترل چیدمانی است که mermaid در اختیارتان می‌گذارد.

گروه‌بندی با زیرگراف‌ها

یک subgraph یک کادر برچسب‌دار دور گره‌ها می‌کشد. زیرگراف‌ها تودرتو می‌شوند و پیکان‌ها می‌توانند آزادانه از مرزهایشان عبور کنند.

flowchart LR
  subgraph api["API"]
    H[Handler] --> S[(Postgres)]
  end
  subgraph worker["Worker"]
    Q[Queue] --> W[Job]
  end
  H --> Q

رنگ و استایل‌دهی

style یک گره را رنگ می‌کند. classDef به‌همراه class مجموعه‌ای از آن‌ها را رنگ می‌کند، که از سه یا چهار گره به بعد همین را می‌خواهید.

flowchart TD
  A[OK] --> B[Failed]
  style A fill:#16a34a,stroke:#333,color:#fff
  classDef bad fill:#dc2626,stroke:#333,color:#fff
  class B bad

رنگ‌ها بخشی از سورس نمودار هستند، پس در خروجی گرفتن دوام می‌آورند و همراه فایل جابه‌جا می‌شوند. اینجا چیزی به تنظیم پوسته در ابزاری که آن را رندر می‌کند وابسته نیست.

یک مثال برای هر نوع نمودار

نمودار توالی

sequenceDiagram
  participant User
  participant API
  participant DB
  User->>API: request
  API->>DB: query
  DB-->>API: rows
  API-->>User: response

نمودار کلاس

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

نمودار حالت

stateDiagram-v2
  [*] --> Idle
  Idle --> Running: start
  Running --> Idle: stop
  Running --> [*]: finish

نمودار رابطه موجودیت

erDiagram
  CUSTOMER ||--o{ ORDER : places
  ORDER ||--|{ LINE_ITEM : contains
  CUSTOMER {
    string name
    string email
  }

نمودار گانت

gantt
  title Project
  dateFormat YYYY-MM-DD
  section Phase 1
  Task 1 :a1, 2026-01-01, 5d
  Task 2 :after a1, 5d

جایی که mermaid خودش رندر می‌شود

• GitHub — یک بلوک با حصار ```mermaid در issue ها، pull request ها، کامنت‌ها و فایل‌های README رندر می‌شود.
• GitLab — همان بلوک با حصار، در issue ها، merge request ها و ویکی.
• Notion — یک بلوک کد با زبان تنظیم‌شده روی Mermaid کنار سورس رندر می‌شود.
• Obsidian — یک بلوک mermaid با حصار در حالت پیش‌نمایش رندر می‌شود.
• سایت‌های مستندات — Docusaurus، MkDocs Material و VitePress همگی از بلوک‌های mermaid پشتیبانی می‌کنند.

این دلیل واقعی نگه‌داشتن نمودارها به‌شکل mermaid به‌جای تصویر است: نمودار در همان فایل متنی چیزی که توصیفش می‌کند زندگی می‌کند و یک بازبینی کد می‌تواند ببیند چه چیزی در آن تغییر کرده.