ورقة صياغة 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 محاطة تُعرض في المشكلات وطلبات السحب والتعليقات وملفات README.
• GitLab — الكتلة المحاطة نفسها، في المشكلات وطلبات الدمج والويكي.
• Notion — كتلة كود بلغة مضبوطة على Mermaid تُعرض بجانب المصدر.
• Obsidian — كتلة mermaid محاطة تُعرض في وضع المعاينة.
• مواقع التوثيق — Docusaurus وMkDocs Material وVitePress كلها تدعم كتل mermaid.

هذا هو السبب الحقيقي للاحتفاظ بالمخططات بصيغة mermaid بدلًا من الصور: يعيش المخطط في نفس الملف النصي للشيء الذي يصفه، ومراجعة الكود يمكنها رؤية ما تغيّر فيه.