الدليل الكامل لمخططات Mermaid.js

ما هو Mermaid.js؟

لماذا تستخدم Mermaid.js؟

• إدارة الإصدارات: المخططات ملفات نصية، لذا يمكن تتبعها في Git إلى جانب الكود
• تحديثات سريعة: غيّر بضعة أسطر نصية بدلاً من إعادة رسم المخططات كاملة
• اتساق: يتولى Mermaid التخطيط والتنسيق تلقائيًا ليضمن مخططات متسقة
• لا حاجة لأدوات تصميم: لا حاجة إلى Visio أو Lucidchart أو أدوات مكلفة أخرى
• التوثيق ككود: احتفظ بالمخططات في نفس المستودع مع التوثيق
• متعدد المنصات: يعمل في المتصفحات وNode.js ويتكامل مع العديد من المنصات
• مجاني ومفتوح المصدر: بلا تكاليف ترخيص ومجتمع نشط
• أنواع متعددة من المخططات: يدعم المخططات الانسيابية ومخططات التسلسل ومخططات الفئات وغيرها

أنواع المخططات المدعومة

يدعم Mermaid مجموعة واسعة من أنواع المخططات لتلبية احتياجات التوثيق المختلفة:

flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Process]
    B -->|No| D[Alternative]
    C --> E[End]
    D --> E

sequenceDiagram
    participant User
    participant API
    participant DB
    User->>API: Request data
    API->>DB: Query
    DB-->>API: Results
    API-->>User: Response

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound()
    }
    class Dog {
        +bark()
    }
    Animal <|-- Dog

stateDiagram-v2
    [*] --> Idle
    Idle --> Loading: Start
    Loading --> Success: Complete
    Loading --> Error: Fail
    Success --> [*]
    Error --> Idle: Retry

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

gantt
    title Project Timeline
    dateFormat YYYY-MM-DD
    section Phase 1
    Design :a1, 2024-01-01, 30d
    Development :a2, after a1, 45d

pie title Distribution
    "Category A" : 42
    "Category B" : 30
    "Category C" : 28

gitGraph
    commit
    branch develop
    checkout develop
    commit
    checkout main
    merge develop

البدء مع Mermaid

أفضل الممارسات

• حافظ على تركيز المخططات على مفهوم واحد أو سير عمل واحد
• استخدم تسميات ذات معنى تصف منطق العمل الفعلي
• قسّم المخططات المعقدة إلى مخططات أصغر مترابطة
• أضف تعليقات باستخدام %% لشرح الأقسام المعقدة
• استخدم اصطلاحات تسمية متسقة عبر مخططاتك
• اختبر مخططاتك في البيئة المستهدفة قبل اعتمادها
• أضف تلميحات الاتجاه (TD, LR) للتحكم في التخطيط عند الحاجة
• استخدم subgraphs لتجميع العقد ذات الصلة في المخططات الانسيابية
• استخدم خيارات التنسيق باعتدال للحفاظ على قابلية القراءة
• قم بإدارة إصدارات ملفات مصدر المخططات مع كودك

حالات استخدام شائعة

موارد إضافية

• التوثيق الرسمي لـ Mermaid
• مستودع Mermaid على GitHub
• مرجع صياغة Mermaid