قواعد مخططات Mermaid: أمثلة لـ Markdown و Obsidian

مخطط Mermaid هو تمثيل مرئي يتم إنشاؤه من كود نصي عادي باستخدام مكتبة Mermaid JS. أطلقه كنوت سفايدكفيست (Knut Sveidqvist) عام 2014، ونما هذا المشروع مفتوح المصدر ليصل إلى أن يصبح المعيار الأساسي للمخططات القائمة على النصوص في وثائق البرمجيات. بحلول عام 2026، أصبحت المنصات الرئيسية مثل GitHub و GitLab وأدوات التوثيق تعرض صيغة Mermaid بشكل أصلي ومباشر.

يشرح هذا الدليل قواعد Mermaid، وأنواع المخططات الأساسية، وطريقة عرضها في Markdown و Obsidian، وخيارات التصدير، وحلول المشكلات الشائعة.

إليك كيف تبدو الصيغة الأساسية:

graph TD
    A[Start] --> B[Process]
    B --> C[Complete]

نهج “المخططات ككود” (diagrams as code) يحسّن إمكانية الصيانة من خلال التحكم في الإصدارات ويُبسط التعاون بين فرق الهندسة. تتناول الأقسام التالية الأنواع الشائعة، والإنشاء خطوة بخطوة، وكيفية تصدير المخططات لأصحاب المصلحة الذين يفضلون الصور الثابتة.

ورقة ملخص قواعد Mermaid (Cheat Sheet)

المخطط	الكلمة المفتاحية للبدء	الاستخدام النموذجي
مخطط انسيابي (Flowchart)	flowchart TD أو flowchart LR	العمليات واتخاذ القرارات
تتابعي (Sequence)	sequenceDiagram	الطلبات، الاستجابات والتفاعل بين الخدمات
العلاقة بين الكيانات (ERD)	erDiagram	كيانات قواعد البيانات والعلاقات بينها
الحالة (State)	stateDiagram-v2	التغيرات في الحالة ودورة الحياة
جانت (Gantt)	gantt	المعالم والجداول الزمنية
الفئات (Class)	classDiagram	نماذج النطاق والأشكال الكائنية

يحتاج كل كتلة Mermaid إلى كلمة مفتاحية واحدة للبدء. يجب أن تظل معرفات العقد (Node IDs) قصيرة وثابتة؛ بينما يمكن أن تحتوي التسميات المرئية على نصوص أطول قابلة للقراءة.

ما هو مخطط Mermaid ولماذا يجب عليك استخدامه؟

يتم إنشاء مخطط Mermaid من صيغة نصية خفيفة الوزن يتم تفسيرها بواسطة مكتبة Mermaid في JavaScript. بدلاً من استخدام واجهة السحب والإفلات، تكتب كود مخطط Mermaid وتقوم المكتبة بتحويله إلى رسومات SVG.

كيف يتحول كود Mermaid إلى رسوم مرئية:

• graph TD; A –> B; يتم عرضه كمخطط انسيابي من الأعلى إلى الأسفل

• كتل sequenceDiagram تتحول إلى مخططات تتابع تظهر تدفق الرسائل

• تعريفات erDiagram تنتج مخططات العلاقة بين الكيانات

الفوائد الرئيسية للمخططات القائمة على النص:

• نص عادي قابل للقراءة بشرياً ويمكن لأي شخص تعديله

• فروق (diffs) متوافقة مع Git تظهر بالضبط ما تم تغييره

• مراجعات كود أسهل في طلبات السحب (Pull Requests)

• لا توجد ملفات مخططات مملوكة تتطلب الإدارة

حالات استخدام عملية لعام 2026:

• توثيق تدفق المصادقة للخدمات الدقيقة (Microservices) باستخدام مخططات التتابع

• رسم خرائط خطوط أنابيب CI/CD من مرحلة التثبيت (Commit) حتى النشر في الإنتاج

• تخطيط معالم إطلاق المنتجات للربع الثاني من عام 2026 باستخدام مخططات جانت

تتكامل مخططات Mermaid بشكل طبيعي مع التوثيق القائم على Markdown، والويكي الداخلي، وبوابات المطورين، مما يسهل عمليات التوثيق في مؤسستك.

أنواع مخططات Mermaid الأساسية

تدعم Mermaid مجموعة واسعة من أنواع المخططات. يقدم هذا القسم نظرة عامة عملية على الأكثر فائدة بدلاً من المرجع الشامل.

أنواع المخططات الرئيسية:

النوع	الكلمة المفتاحية	الأفضل لـ
المخططات الانسيابية	graph TD / flowchart LR	تدفقات العمليات، أشجار القرار
مخططات التتابع	sequenceDiagram	استدعاءات API، تفاعلات الخدمات
مخططات الفئات	classDiagram	نماذج الكائنات، تصميم النطاق
مخططات الحالة	stateDiagram-v2	حالات دورة الحياة، تدفقات العمل
مخططات العلاقة بين الكيانات	erDiagram	تصميم مخطط قاعدة البيانات
رحلة المستخدم	journey	رسم خرائط تجربة العملاء
مخططات جانت	gantt	الجداول الزمنية، خارطة الطريق
المخططات الدائرية	pie	تصور البيانات النسبية
مخططات Git	gitGraph	استراتيجيات الفروع (Branching)

أمثلة من الواقع:

• مخططات تتابع لتدفقات الواجهة الأمامية ← بوابة API ← API خدمة الدفع

• مخططات جانت لخارطة طريق ميزات الربع الثاني من عام 2026 مع التبعيات

• مخططات حالة ودورة حياة الطلب: قيد الانتظار ← مدفوع ← تم الشحن ← تم التسليم

المخططات الانسيابية، ومخططات التتابع، ومخططات ER، ومخططات الحالة هي الأكثر شيوعاً لفرق البرمجيات. بينما تميل فرق المنتجات والعمليات إلى استخدام رحلة المستخدم، وجانت، والمخططات الدائرية لعمليات العملاء والأعمال.

sequenceDiagram
    participant User
    participant API
    User->>API: POST /login
    API-->>User: 200 OK + Token

كيفية إنشاء مخططات Mermaid

يبدأ إنشاء المخططات الانسيابية بسرعة بفهم الهيكل الأساسي. يمكنك إنشاء المخططات باستخدام أي محرر نصوص وصيغة Mermaid.

العملية خطوة بخطوة:

1. ابدأ بكلمة مفتاحية للمخطط (graph TD, sequenceDiagram, gantt)

2. حدد العقد أو المشاركين باستخدام المعرفات والتسميات

3. اربط العناصر بالأسهم أو العلاقات

4. أضف التسميات والتجميعات حسب الحاجة

إليك مخطط انسيابي لعملية تسجيل الدخول يعمل بالكامل:

graph TD
    U[User] --> LP[Login Page]
    LP --> AS[Auth Service]
    AS --> DB[(User Database)]
    AS -->|Success| DASH[Dashboard]
    AS -->|Failure| ERR[Error Page]

أنواع الأسهم والتسميات:

• –> ينشئ سهماً موجهاً قياسياً

• –>|label| يضيف نصاً مشروطاً على الوصلات

• — يرسم خطاً بدون رأس سهم

• -.-> ينشئ سهماً منقطاً للعلاقات غير المباشرة

تقوم Mermaid بتنسيق العقد تلقائياً باستخدام خوارزميات التخطيط ELK. ركز على الهيكل المنطقي والتسمية بدلاً من تحديد المواضع يدوياً—لا داعي لكتابة كود إضافي للمحاذاة.

أين يمكنك استخدام مخططات Mermaid في عام 2026

تدعم العديد من المنصات الرئيسية الآن Mermaid إما بشكل أصلي أو من خلال التوسيعات، مما يسهل البدء فوراً.

البيئات الرئيسية:

• GitHub و GitLab: عرض أصلي في README.md والوثائق والمشكلات والويكي

• مولدات المواقع الثابتة: Docusaurus و MkDocs و Sphinx مع الإضافات

• بوابات المطورين الداخلية: Backstage وتطبيقات React المخصصة

• أدوات تدوين الملاحظات: Notion و Obsidian مع دعم مدمج لمخططات Mermaid

يدعم Visual Studio Code وبيئات JetBrains المعاينة المباشرة عبر الإضافات، مما يتيح لك معاينة المخططات أثناء الكتابة. يساعد هذا في اكتشاف أخطاء القواعد قبل تثبيت التغييرات (Commit).

تتطلب بعض المنصات مثل Confluence Cloud إضافات من المتجر. غالباً ما تخزن الفرق المخططات خارجياً في مستودعات الكود مع الاحتفاظ بالصور المصدّرة بجانبها لسهولة الرؤية.

عرض مخططات Mermaid على منصات مختلفة

يحول العرض نص Mermaid إلى رسوم SVG/HTML مرئية. تعتمد الطريقة على كيفية عمل مخطط Mermaid مع المنصة المستضيفة.

النمط العام: ضع كود Mermaid في كتل كود محدودة مع معرف اللغة mermaid. تعترض GitHub و GitLab ومولدات التوثيق هذه الكتل وتعرضها تلقائياً عند عرضها في المتصفحات.

للتطوير المحلي، توفر التوسيعات معاينة مباشرة. في توثيق Sphinx، قم بتمكين العرض من خلال إضافات مثل sphinxcontrib-mermaid التي تعالج المخططات المنشأة أثناء البناء.

عرض Mermaid في ملفات Markdown

لثبيت عرض Mermaid في Markdown:

1. استخدم ثلاثة رموز backticks لفتح كتلة كود

2. حدد mermaid كمعرف للغة

3. أضف تعريف المخطط في الداخل

4. أغلق بثلاثة رموز backticks

```mermaid
flowchart LR
    A[Step 1] -->|Process| B[Step 2]
    B -->|Complete| C[Step 3]
```

• تدعم GitHub و GitLab ومواقع التوثيق الحديثة هذا النمط مباشرة

• اختبر العرض في بيئة معاينة قبل الدمج مع الإنتاج

• يعمل المظهر الافتراضي لمخطط Mermaid بشكل ممتاز لمعظم الوثائق

عرض Mermaid في Obsidian

يعرض Obsidian مخططات Mermaid من كتلة كود mermaid المحدودة في عرض القراءة والمعاينة المباشرة. الدعم مدمج تلقائياً، لذا لا تحتاج إلى إضافة مجتمعية للمخططات الأساسية.

إذا لم يتم عرض المخطط:

1. تأكد من أن السطر الافتتاحي هو ```mermaid بالضبط.
2. تحقق من السطر الأول للحصول على كلمة مفتاحية صالحة مثل flowchart LR.
3. استبدل التسميات المليئة برموز الترقيم بتسميات بين اقتباسات، مثل A["Review: blocked?"].
4. قلل المثال إلى عقدتين، ثم أعد إضافة الأسطر حتى تظهر الصيغة المسببة للمشكلة.
5. تحقق مما إذا كانت نسخة Obsidian المثبتة لديك تدعم أحدث قواعد Mermaid التي قمت بنسخها.

للحصول على قواعد Markdown الخاصة بـ Obsidian، راجع ورقة قواعد التنسيق لـ Obsidian.

عرض Mermaid في بيئات IDE والأدوات المحلية

تتيح إضافة Visual Studio Code لـ Mermaid المعاينة المباشرة جنباً إلى جنب أثناء تعديل المخططات. توفر عدة إضافات تظليل القواعد واقتراحات إصلاح المخططات المعقدة.

تقدم بيئات JetBrains إمكانيات مماثلة عبر الإضافات، وتتضمن غالباً تلميحات الأخطاء وخيارات التصدير. يمكن لزر إصلاح المخطط في بعض الأدوات إصلاح المشكلات الشائعة تلقائياً.

تساعد المعاينات المحلية في اكتشاف الأخطاء قبل الرفع إلى مستودعات Git. اعتمد مجموعة إضافات موصى بها في وثائق إعداد المطورين لديك.

تصدير ومشاركة مخططات Mermaid

بينما تعمل خيارات التحرير القائمة على الكود بشكل ممتاز للمطورين، يفضل أصحاب المصلحة غالباً الصور الثابتة للعروض التقديمية في Microsoft PowerPoint والتقارير.

صيغ التصدير الشائعة:

• PNG: مشاركة سريعة عبر أدوات المراسلة

• SVG: رسومات متجهة عالية الجودة للسلايدات

• PDF: حزم توثيق قابلة للطباعة

تختلف سير عمل التصدير حسب الأداة. يتضمن بعضها زر تصدير مدمج، بينما تطلب أدوات أخرى محرر Mermaid Chart أو أدوات عبر الإنترنت مثل Mermaid Live Editor. يمكن لأدوات سطر الأوامر إنشاء الصور بدفعات من ملفات متعددة كجزء من CI/CD.

احتفظ دائماً بمصدر Mermaid الأصلي جنباً إلى جنب مع الأصول المصدّرة حتى تظل المخططات قابلة للتعديل.

تحويل مخططات Mermaid إلى صيغ صور

سير عمل مصغر باستخدام محرر عبر الإنترنت:

1. افتح Mermaid Live Editor في متصفحك

2. الصق كود Mermaid الخاص بك أو استخدم مخططات عينة كقوالب

3. اضبط إعدادات نمط المخطط

4. قم بتكوين مظهر متعدد إذا لزم الأمر (خيارات الوضع الداكن والفيض المتاحة)

5. انقر على “Download SVG” أو “Download PNG”

تأكد من أن المخططات المصدّرة تستخدم خطوطاً وألواناً متناسقة تتماشى مع إرشادات العلامة التجارية. ستصبح لقطات الشاشة من GitHub نقطية (rasterized) وقد لا تتوسع بشكل جيد—استخدم تصدير SVG للعروض التقديمية كلما أمكن.

أفضل الممارسات والقيود لمخططات Mermaid

Mermaid أداة قوية ولكنها تعمل بشكل أفضل مع نطاق وهيكل مدروسين لمهام التخطيط.

التوصيات:

• حدد كل مخطط بمفهوم واحد مرركز

• استخدم تسميات عقد وصفية وأنماط تسمية متسقة

• قم بتجميع الخطوات ذات الصلة باستخدام كتل subgraphs

• احتفظ بالمخططات المعقدة كملفات منفصلة بدلاً من مخطط واحد ضخم

القيود الواجب مراعاتها:

• تصبح الأنظمة الكبيرة والمكثفة صعبة الإدارة ككود

• التحكم في التخطيط تقريبي—لا يوجد تحديد مواضع بدقة البكسل

• التنسيق أقل مرونة من أدوات التخطيط التقليدية أو السبورة البيضاء

• ليست مثالية للتصميم المرئي المفاهيمي أو النماذج الأولية للواجهات (UI Mockups)

استخدم Mermaid لنظرة عامة على الهندسة المعمارية وتدفقات العمل. انتقل إلى أدوات متخصصة عندما تتطلب الحاجة تخطيطات دقيقة بالبكسل أو شبكات معقدة. قد تظل هناك حاجة لمحرر مرئي للمخططات في حالات استخدام معينة.

البدء السريع مع مخططات Mermaid

قائمة تحقق لللمستخدمين الجدد:

1. اختر نوع مخطط واحد (عادة المخطط الانسيابي لإنشاء العمليات بسهولة)

2. قم بتثبيت إضافة تدعم المحرر المرئي أو الدردشة بالذكاء الاصطناعي أو افتح Mermaid Live Editor

3. ارسم عملية حقيقية من مشروعك الحالي—مثل خط أنابيب النشر لعام 2026

4. كرر ووسع كلما تعلمت أنماط الصيغ

الموارد الرئيسية:

• التوثيق الرسمي لـ Mermaid للحصول على مرجع كامل للقواعد

• Mermaid Live Editor للتجربة مع ميزات التوليد بالذكاء الاصطناعي المدمجة

• إضافات VS Code مع مقتطفات الكود والقوالب

• النظر في حساب أساسي على منصات التعاون لميزات الفرق

أضف قسم “إرشادات المخططات” إلى دليل الهندسة الخاص بك يغطي اتفاقيات التسمية، وأنوع المخططات المفضلة، والأذونات. تجد بعض الفرق أن الأوصاف بلغة طبيعية إلى جانب أدوات الذكاء الاصطناعي المدمجة تسرع إنشاء المخططات لاي مستوى مهارة تقنية.

إن اعتماد مخططات Mermaid يربط التوثيق لديك بنفس ممارسات المراجعة والأتمتة المستخدمة للكود المصدري. سواء كنت مهندس تعلم آلة توثق خطوط أنابيب النماذج أو مدير مشاريع ترسم تدفقات العمل، فإن Mermaid تجلب رسومات مرئية خاضعة للتحكم في الإصدارات لفر يقك. ابدأ بمخطط واحد اليوم.