غالبًا ما تصبح المخططات الفنية قديمة لأن تحريرها يتطلب العثور على ملف التصميم الأصلي، وفتح تطبيق منفصل، وتصدير صورة أخرى.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 طويل يجعل من الصعب عزل الأخطاء النحوية.تكون حلقة المعاينة المركزة أسرع:
- افتح معاينة مخطط Mermaid.
- قم بلصق تعريف المخطط فقط، بدون سياج الكود الخارجي.
- تقديم الرسم التخطيطي.
- اقرأ أي خطأ في بناء الجملة وقم بتصحيح المنطقة المشار إليها.
- انسخ المسيجة التي تم إنشاؤها Markdown.
- قم بتنزيل SVG عندما تحتاج الوجهة إلى أصل ثابت.
- اختبار 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 block | GitHub عرض المستندات في ملفات Markdown، والمشكلات، والمناقشات، وطلبات السحب، ومواقع wiki |
| غيت لاب | استخدم كتلة التعليمات البرمجية Mermaid في GitLab Flavored Markdown | يقوم GitLab بتوثيق إصدار Mermaid المدعوم؛قد تختلف عمليات التثبيت المُدارة ذاتيًا |
| Obsidian | استخدم سياجًا mermaid كتلة في ملاحظة | Obsidian يمكن أن يتغير العارض والميزات المدعومة بين الإصدارات |
| مادة لـ MkDocs | تكوين سياج مخصص Mermaid | يتطلب تكامل السمة الأصلية توثيقًا pymdownx.superfences configuration |
| محلل عام Markdown | غالبا ما يعرض الكود فقط | Mermaid يتطلب العرض عادةً تكامل JavaScript أو مكون إضافي للإنشاء |
تحقق من الوثائق الرسمية الحالية قبل الاعتماد على ميزة أحدث:
- GitHub: إنشاء المخططات
- نكهة GitLab Markdown
- Obsidian: صيغة التنسيق المتقدمة
- مادة لـ MkDocs: الرسوم البيانية
- Mermaid مرجع بناء الجملة
بالنسبة لموقع التوثيق الذي تتحكم فيه، قم بتثبيت الإصدار التابع 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 المحرر، وحافظ على تركيز الرسم التخطيطي بدرجة كافية حتى يتمكن المساهم المستقبلي من فهمه وتحديثه دون إعادة رسم الصفحة بأكملها.