mermaid markdown diagrams flowchart documentation

Mermaid في Markdown: إنشاء مخططات انسيابية وتسلسلية والمزيد

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

W
WordToMD الفريق
·

غالبًا ما تصبح المخططات الفنية قديمة لأن تحريرها يتطلب العثور على ملف التصميم الأصلي، وفتح تطبيق منفصل، وتصدير صورة أخرى.Mermaid يتبع أسلوبًا مختلفًا: يتم تعريف الرسم التخطيطي كنص ويتم تخزينه بجانب الوثائق.

لإضافة Mermaid إلى Markdown، ضع تعريف المخطط داخل كتلة التعليمات البرمجية المسيجة مع mermaid معرف اللغة.استخدم معاينة مخطط Mermaid لعرض الصيغة محليًا، أو تصحيح الأخطاء، أو نسخ السياج Markdown الكامل، أو تنزيل SVG.

يبدأ هذا الدليل بمخطط انسيابي صغير ويتجه نحو التسلسل والفئات وجانت والخريطة الذهنية والرسوم البيانية للعلاقة بين الكيانات.

Mermaid في 30 ثانية

تبدو الكتلة الأساسية Mermaid كما يلي:

```mermaid
flowchart LR
  Draft --> Review
  Review --> Publish
```

يخبر السياج الافتتاحي العارض المتوافق أن المحتوى هو بناء الجملة Mermaid. flowchart LR يحدد مخططًا انسيابيًا مرتبًا من اليسار إلى اليمين.الخطوط المتبقية تحدد العقد والاتصالات.

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

لماذا نستخدم المخططات النصية؟

Mermaid مفيد بشكل خاص عندما يكون الرسم التخطيطي:

  • ينتمي إلى الوثائق التي يتم التحكم في إصدارها؛
  • التغييرات مع التعليمات البرمجية أو الإجراءات؛
  • يحتاج إلى اختلافات ذات مغزى في طلب السحب؛
  • يستخدم الأشكال والعلاقات القياسية؛
  • يجب أن يكون قابلاً للتحرير بدون ملف تصميم خاص؛
  • يجب أن يتم تجديده في السمات الفاتحة والداكنة.

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

مثال 1: مخطط انسيابي

تصف المخططات الانسيابية عملية أو قرار أو قاعدة توجيه.

```mermaid
flowchart TD
  A[Choose a DOCX file] --> B{File valid?}
  B -->|Yes| C[Convert to Markdown]
  B -->|No| D[Show an error]
  C --> E[Review the output]
  E --> F[Copy or download]
```

بناء الجملة الرئيسي:

  • TD يعني من الأعلى إلى الأسفل.
  • LR يعني من اليسار إلى اليمين.
  • [Text] ينشئ عقدة عملية مستطيلة.
  • {Text} ينشئ عقدة القرار.
  • --> ينشئ اتصالاً اتجاهيًا.
  • -->|Label| يضيف نصًا إلى الاتصال.

استخدم معرفات العقدة القصيرة والمستقرة مثل A or validate.احتفظ بالملصق المرئي بين قوسين بحيث لا يتطلب تغيير الصياغة تغيير كل اتصال.

إضافة رسم بياني فرعي

الخطوات المتعلقة بمجموعة الرسوم البيانية الفرعية:

```mermaid
flowchart LR
  subgraph Browser
    Upload[Choose file] --> Convert[Convert locally]
  end

  subgraph Output
    Preview[Preview Markdown] --> Save[Download file]
  end

  Convert --> Preview
```

استخدم الرسوم البيانية الفرعية عندما تقوم المجموعة بتوصيل الملكية أو حدود النظام أو المراحل.لا تضف صندوقًا للزينة فقط.

مثال 2: مخطط التسلسل

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

```mermaid
sequenceDiagram
  autonumber
  actor User
  participant Browser
  participant Converter

  User->>Browser: Select DOCX file
  Browser->>Converter: Pass local file data
  Converter-->>Browser: Return Markdown
  Browser-->>User: Show editable preview
```

الأسهم الشائعة:

  • ->> يرسل رسالة قوية.
  • -->> يرسل استجابة متقطعة.
  • participant تعلن عن نظام أو خدمة.
  • actor تعلن عن دور بشري أو خارجي.
  • autonumber يقوم بتسمية التفاعلات بالترتيب.

التركيز على سيناريو واحد.يصبح الرسم التخطيطي التسلسلي الذي يحاول إظهار كل بديل وكل وظيفة داخلية أكثر صعوبة في الفهم من الكود.

إظهار المسار البديل

```mermaid
sequenceDiagram
  participant Client
  participant API

  Client->>API: POST /documents
  alt Valid request
    API-->>Client: 201 Created
  else Invalid request
    API-->>Client: 400 Bad Request
  end
```

الاستخدام alt, elseو end للفروع ذات المعنى.إذا كان الفرع يحتاج إلى عدة صفحات من الشرح، رابط النثر أسفل الرسم التخطيطي.

مثال 3: مخطط الفئة

تصف الرسوم البيانية للفئة الأنواع والخصائص والعمليات والميراث والعلاقات.

```mermaid
classDiagram
  class Document {
    +String name
    +String content
    +convert()
  }

  class MarkdownDocument {
    +String frontmatter
    +render()
  }

  Document <|-- MarkdownDocument
```

ينص هذا المثال على ذلك MarkdownDocument يرث من Document.استخدم الرسوم البيانية للفئة لنموذج مفاهيمي، وليس كبديل تلقائي للوثائق المرجعية الكاملة API.

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

مثال 4: مخطط جانت

تعرض مخططات جانت المهام عبر الوقت.وهي مفيدة لخطط الإصدار والترحيل ومشاريع التوثيق.

```mermaid
gantt
  title Documentation migration
  dateFormat YYYY-MM-DD

  section Preparation
  Inventory content :done, inventory, 2026-11-03, 3d
  Define templates  :done, templates, after inventory, 2d

  section Migration
  Convert documents :active, convert, 2026-11-08, 7d
  Editorial review  :review, after convert, 5d

  section Publish
  Final validation  :validate, after review, 2d
```

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

مثال 5: خريطة ذهنية

تنظم الخرائط الذهنية الأفكار حول موضوع مركزي.

```mermaid
mindmap
  root((Markdown quality))
    Structure
      Headings
      Lists
      Tables
    Accessibility
      Alt text
      Link text
      Reading order
    Publishing
      GitHub
      Obsidian
      Documentation site
```

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

مثال 6: مخطط العلاقة بين الكيان

تصف مخططات ER كيانات البيانات والعلاقات بينها.

```mermaid
erDiagram
  AUTHOR ||--o{ DOCUMENT : writes
  DOCUMENT ||--o{ REVISION : contains
  DOCUMENT }o--o{ TAG : uses

  AUTHOR {
    string id
    string name
  }

  DOCUMENT {
    string id
    string title
    datetime published_at
  }
```

استخدم مخطط ER لشرح النموذج والمخطط أو ملف الترحيل لتحديد التنفيذ.قد يحذف الرسم التخطيطي الفهارس والقيود والحقول التي لا تتعلق بالتفسير الحالي.

معاينة Mermaid قبل النشر

كتابة المخططات مباشرة في مستند Markdown طويل يجعل من الصعب عزل الأخطاء النحوية.تكون حلقة المعاينة المركزة أسرع:

  1. افتح معاينة مخطط Mermaid.
  2. قم بلصق تعريف المخطط فقط، بدون سياج الكود الخارجي.
  3. تقديم الرسم التخطيطي.
  4. اقرأ أي خطأ في بناء الجملة وقم بتصحيح المنطقة المشار إليها.
  5. انسخ المسيجة التي تم إنشاؤها Markdown.
  6. قم بتنزيل SVG عندما تحتاج الوجهة إلى أصل ثابت.
  7. اختبار Markdown النهائي في منصته الحقيقية.

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

أخطاء Mermaid شائعة

نوع المخطط مفقود

غير صحيح:

A --> B

صحيح:

flowchart LR
  A --> B

يحدد السطر الأول قواعد الرسم التخطيطي.

علامات الترقيم في التسمية تكسر التحليل

اقتباس التسميات المعقدة:

flowchart LR
  A["Parse input: DOCX, HTML, or text"] --> B["Create Markdown"]

يعد هذا مفيدًا بشكل خاص للأقواس وعلامات الترقيم والتسميات التي تشبه بناء الجملة.

يتم استخدام Word محجوز بشكل غير متوقع

Mermaid القواعد النحوية لها كلمات أساسية.تحذر وثائق المخطط الانسيابي الرسمية على وجه التحديد من تلك الأحرف الصغيرة end يمكن أن يكسر المخطط الانسيابي.قم بكتابته بحرف كبير أو ضع النص المرئي داخل تسمية العقدة المقتبسة:

flowchart LR
  Start --> Finish["End"]

سياج الكود غير صحيح

ينتمي معرف اللغة مباشرة بعد علامات الفتح الخلفية:

```mermaid
flowchart LR
  A --> B
```

لا تقم بوضع مسافة بادئة للسياج الكامل إلا إذا تطلب بناء الجملة Markdown المحيط ذلك.

يعمل في منصة واحدة وليس في منصة أخرى

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

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

توافق النظام الأساسي

يجب اختبار التوافق بدلاً من افتراضه:

المنصةالنهج الموثق الحاليملاحظة هامة
GitHubاستخدم سياجًا mermaid blockGitHub عرض المستندات في ملفات Markdown، والمشكلات، والمناقشات، وطلبات السحب، ومواقع wiki
غيت لاباستخدم كتلة التعليمات البرمجية Mermaid في GitLab Flavored Markdownيقوم GitLab بتوثيق إصدار Mermaid المدعوم؛قد تختلف عمليات التثبيت المُدارة ذاتيًا
Obsidianاستخدم سياجًا mermaid كتلة في ملاحظةObsidian يمكن أن يتغير العارض والميزات المدعومة بين الإصدارات
مادة لـ MkDocsتكوين سياج مخصص Mermaidيتطلب تكامل السمة الأصلية توثيقًا pymdownx.superfences configuration
محلل عام Markdownغالبا ما يعرض الكود فقطMermaid يتطلب العرض عادةً تكامل JavaScript أو مكون إضافي للإنشاء

تحقق من الوثائق الرسمية الحالية قبل الاعتماد على ميزة أحدث:

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

Mermaid وإمكانية الوصول

لا يقوم ملف SVG المعروض بتوصيل معناه تلقائيًا إلى كل قارئ.تعامل مع الرسم التخطيطي باعتباره ملخصًا مرئيًا وقدم شرحًا مكافئًا في النثر القريب.

بالنسبة للمخطط الانسيابي السابق للتحويل، قم بإضافة نص مثل:

يقوم المستخدم بتحديد ملف DOCX.يتم تحويل الملفات الصالحة محليًا وعرضها للمراجعة؛الملفات غير الصالحة تنتج خطأ.ويمكن للمستخدم بعد ذلك نسخ أو تنزيل الملف الذي تمت مراجعته Markdown.

ممارسات إمكانية الوصول:

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

الكود المصدري مفيد للمؤلفين، لكنه ليس بالضرورة بديلاً جيدًا للنص للقراء.

تصميم الرسوم البيانية التي تظل قابلة للقراءة

احتفظ بغرض واحد لكل مخطط

يجب أن يجيب الرسم التخطيطي على سؤال مثل "ماذا يحدث بعد فشل الطلب؟"أو "ما الخدمة التي تمتلك كل مخزن بيانات؟"إذا حاول شرح النظام بأكمله، قم بتقسيمه.

تفضيل التسميات القصيرة

ضع تفسيرات مفصلة في النثر.تفرض الملصقات الطويلة عقدًا ضيقة والتفافًا غريبًا للخطوط ورسومًا بيانية كبيرة على شاشات الهاتف المحمول.

استخدم الاتجاه عمدا

يعمل التدفق من اليسار إلى اليمين بشكل جيد للعمليات القصيرة ومسارات الطلب.غالبًا ما يناسب التدفق من أعلى إلى أسفل الشاشات الضيقة بشكل أفضل.معاينة كليهما قبل الالتزام.

الحد من التصميم المرئي

يمكن أن تتعارض الألوان المخصصة مع الوضع الداكن أو سمات النظام الأساسي.ابدأ بالإعدادات الافتراضية للعارض.أضف الأنماط فقط عندما تنقل المعنى وتظل قابلة للقراءة في جميع السمات المطلوبة.

احتفظ بالمصدر بالقرب من شرحه

قم بتخزين الكتلة Mermaid في نفس الملف Markdown عندما يكون ذلك ممكنًا.وهذا يجعل النثر والرسم البياني يتغيران معًا في مراجعة واحدة.

Mermaid مقابل صورة ثابتة

اختر Mermaid عندما:

  • يتغير الرسم التخطيطي بشكل متكرر؛
  • اختلافات المصدر ذات قيمة؛
  • يستخدم التخطيط أنواع المخططات القياسية؛
  • تعرض منصة النشر Mermaid بشكل موثوق.

اختر SVG أو PNG عندما:

  • يتطلب التصميم تخطيطًا يدويًا دقيقًا؛
  • الوجهة لا تعرض Mermaid;
  • يجب أن يظل المظهر الدقيق ثابتًا؛
  • تتطلب المشاركة الخارجية وجود أصل مستقل.

الهجين المفيد هو الحفاظ على مصدر Mermaid وتصدير SVG للوجهات التي لا يمكنها عرضه.احتفظ بالمصدر بجانب الأصل المصدر وقم بتوثيق كيفية تجديده.

الاستخدام Markdown إلى صورة لمحتوى Markdown القابل للمشاركة، أو قم بتنزيل SVG مباشرة من معاينة مخطط Mermaid عندما يكون المخطط نفسه هو الأصل.

FAQ

هل Mermaid جزء من المعيار Markdown؟

رقم أ مسيجة mermaid block هو امتداد معترف به من قبل التطبيقات المتوافقة وأنظمة البناء.قد يعرضها المحلل اللغوي Markdown الأساسي كرمز عادي.

هل يقوم GitHub بعرض الرسوم البيانية Mermaid؟

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

هل يمكنني استخدام Mermaid في Obsidian؟

Obsidian وثائق المساعدة الرسمية لـ Mermaid كتل تخطيطية مسيجة على طراز Mermaid في الملاحظات.يمكن أن يتغير دعم الميزات مع عارض التطبيق، لذا تحقق من أنواع المخططات المعقدة أو المقدمة حديثًا في الإصدار المثبت لديك.

هل يمكن لـ Mermaid استبدال وثائق الهندسة المعمارية؟

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

لماذا يظهر الرسم التخطيطي الخاص بي بشكل مختلف في الوضع المظلم؟

قد تطبق الأنظمة الأساسية سمات Mermaid ومتغيرات CSS وخطوط وخلفيات مختلفة.تجنب الألوان المرمزة حتى تختبر كلا الموضوعين.

هل يجب علي الالتزام بملفات SVG المصدرة؟

قم بتنفيذ SVG عندما تحتاج وجهة النشر إلى أصل ثابت أو يجب أن تظل النتيجة المقدمة مستقرة.احتفظ أيضًا بمصدر Mermaid وعملية تجديد موثقة لمنع انحراف الإصدارين.

هل Mermaid آمن للمخططات السرية؟

تعتمد السرية على سير عمل المحرر والنشر.تعرض معاينة WordToMD الرسم التخطيطي في متصفحك، ولكن نشر Markdown أو SVG إلى مستودع أو موقع يتبع عناصر التحكم في الوصول لتلك الوجهة.

النتيجة

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

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