عارض ومحرر Markdown مع Mermaid

مستند Markdown

اكتب ملف Markdown أو الصقه أو افتحه وشاهد المعاينة فورًا كما في GitHub: الجداول وقوائم المهام والحواشي والتنبيهات ومخططات Mermaid وصيغ LaTeX والكود المميّز. بعد ذلك يمكنك تنزيله بصيغة HTML أو حفظه بصيغة PDF. تتم معالجة كل شيء في متصفحك.

الفهرس

تمرير متزامن

احترام فواصل الأسطر

---
title: "مستند تجريبي"
tags: [markdown, mermaid, katex]
---

# مستند تجريبي

عدّل هذا النص وشاهد النتيجة فورًا. يدعم **الخط العريض**، *المائل*، ~~المشطوب~~، `الكود`، الروابط مثل https://ittools.tech والحواشي[^1].

> [!NOTE]
> تنبيهات GitHub تعمل أيضًا: جرّب TIP أو IMPORTANT أو WARNING أو CAUTION.

## المهام والجداول

- [x] كتابة ملف README
- [ ] إضافة مخطط

| HTTP | Endpoint | Status |
|:-------|:-----|-------:|
| `GET` | `/api/users` | 200 |
| `POST` | `/api/users` | 201 |
| `DELETE` | `/api/users/42` | 204 |

```typescript
async function getUser(id: number): Promise<User> {
  const response = await fetch(`/api/users/${id}`);
  if (!response.ok) throw new Error(response.statusText);
  return response.json();
}
```

## المخططات والصيغ

```mermaid
sequenceDiagram
    participant C as App
    participant A as API
    participant D as DB
    C->>A: GET /api/users/42
    A->>D: SELECT * FROM users WHERE id = 42
    D-->>A: row
    A-->>C: 200 OK (JSON)
```

```mermaid
flowchart LR
    A[Commit] --> B{Tests OK?}
    B -- ✓ --> C[Build]
    B -- ✗ --> D[Fix]
    D --> A
    C --> E[Deploy]
```

$$
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
$$

Euler: $e^{i\pi} + 1 = 0$

</details>

[^1]: تتم معالجة كل شيء في متصفحك؛ لا يُرسَل المستند إلى أي خادم.

الكلمات: 0 · الأسطر: 0 · وقت القراءة: 0 د

كيف يعمل

Markdown هو تنسيق ملفات README والتوثيق التقني والويكي والملاحظات في كل أدوات التطوير تقريبًا، لكن كل منصة تضيف إليه امتداداتها الخاصة. يتبع هذا العارض GitHub Flavored Markdown (GFM)، وهو الإصدار الأكثر استخدامًا: فإلى جانب الأساسيات، يعرض الجداول وقوائم المهام والنص المشطوب والروابط التلقائية والحواشي وتنبيهات NOTE وTIP وIMPORTANT وWARNING وCAUTION.

تتحول كتل الكود الموسومة بـ mermaid إلى مخططات (انسيابية، تسلسلية، فئات، حالات، كيان-علاقة، Gantt، Git وغيرها)، وتُرسم الصيغ الموضوعة بين علامتي $ باستخدام KaTeX، ويُميَّز باقي الكود حسب اللغة المحددة. وإذا بدأ المستند بكتلة YAML بين سطرين ---، مثل تلك المستخدمة في Jekyll أو Hugo أو Docusaurus، فإنها تُعرض كجدول منفصل.

لا يغادر المستند متصفحك. يُنظَّف أي HTML يحتويه قبل عرضه، لذا فإن فتح ملف README من مصدر خارجي لا يشغّل أي سكربتات، ولا تُنزَّل مكتبات المخططات والصيغ إلا إذا كان المستند يستخدمها.

أمثلة

```mermaid
flowchart LR
  A[Commit] --> B[Build] --> C[Deploy]
```

Commit → Build → Deployتُرسم كتلة الكود ذات اللغة mermaid كمخطط. وإذا احتوت على خطأ في الصياغة، يبقى الكود ظاهرًا وتحته رسالة Mermaid.

## Getting Started
## API v2.0 (beta)
## Getting Started

#getting-started · #api-v20-beta · #getting-started-1تحصل العناوين على نفس الـ id الذي يمنحه لها GitHub: أحرف صغيرة، والمسافات مستبدلة بشرطات، دون علامات ترقيم، مع رقم في النهاية إذا تكررت. وبذلك يعمل رابط مثل [نص](#getting-started) هنا وفي المستودع بالطريقة نفسها.

Line one
Line two

<p>Line one
Line two</p>  →  <p>Line one<br>Line two</p>

في Markdown القياسي لا يؤدي فاصل الأسطر المفرد إلى إنهاء الفقرة؛ بل يجب ترك سطر فارغ أو إنهاء السطر بمسافتين. أما تعليقات GitHub والـ issues فتحترمه: لرؤية النص بهذا الشكل، فعّل خيار احترام فواصل الأسطر.

> [!WARNING]
> Breaking change in v3.

⚠ Warning — Breaking change in v3.يُعرض الاقتباس الذي يبدأ بـ [!NOTE] أو [!TIP] أو [!IMPORTANT] أو [!WARNING] أو [!CAUTION] كتنبيه ملوّن، تمامًا كما في GitHub. وعلى المنصات التي لا تدعمها يظهر كاقتباس عادي.

حالات الاستخدام

التحقق من شكل ملف README أو CHANGELOG قبل رفعه إلى المستودع.
قراءة ملف .md تم تنزيله دون تثبيت محرر: يُفتح عبر الزر أو بسحبه وإفلاته.
تجربة مخططات Mermaid للبنية المعمارية أو التدفقات أو التسلسلات وتصحيح الصياغة مع المعاينة المباشرة.
تحويل التوثيق إلى صفحة HTML مستقلة أو ملف PDF لمشاركته مع من لا يستخدمون Git.
كتابة ملاحظات أو توثيق تقني يتضمن صيغًا رياضية بترميز LaTeX.
عرض نص Markdown الذي يُرجعه مساعد ذكاء اصطناعي بتنسيقه وجداوله وكتل الكود فيه.

الأسئلة الشائعة

ما أنواع مخططات Mermaid التي يمكن رسمها؟

جميع الأنواع التي يوفرها Mermaid: flowchart, sequenceDiagram, classDiagram, stateDiagram-v2, erDiagram, gantt, pie, journey, gitGraph, mindmap, timeline, quadrantChart, sankey, xychart, block, architecture وkanban وغيرها. تستخدم المخططات ألوانًا فاتحة أو داكنة حسب سمة الموقع، وتُرسم في الوضع الصارم: فلا يمكن لنص التسميات حقن HTML أو تشغيل كود عند النقر.

كيف أكتب صيغة رياضية؟

بين علامتي $ للصيغة ضمن السطر، مثل $a^2 + b^2 = c^2$، وبين $$ أو في كتلة كود بلغة math للصيغة المتوسطة في سطر مستقل. الصياغة هي صياغة LaTeX التي يدعمها KaTeX. لكتابة علامة $ حرفية، كما في الأسعار، ضع قبلها شرطة مائلة عكسية؛ ومع ذلك فإن "$5 و $10" لا تُعامل كصيغة، لأن علامة $ الثانية تسبقها مسافة ويليها رقم.

هل يمكنني استخدام HTML داخل Markdown؟

نعم، كما في GitHub: وسوم مثل details وsummary للأقسام القابلة للطي، وkbd للمفاتيح، وsub وsup، وimg مع الحجم، أو p مع align. وقبل العرض تُزال السكربتات وسمات الأحداث مثل onclick وروابط javascript: ووسوم style وform، لذا لا يمكن لمستند من مصدر خارجي تشغيل كود أو تغيير بقية الصفحة.

كيف أحوّله إلى PDF؟

من تصدير، يفتح خيار طباعة أو حفظ بصيغة PDF نافذة الطباعة بالمستند وحده دون واجهة الموقع، ومنها تختار حفظ بتنسيق PDF. ويُتجنَّب قدر الإمكان تقسيم الجداول وكتل الكود والمخططات بين الصفحات. وإذا كنت تفضّل ملفًا للنشر، فإن تنزيل .html يُنشئ صفحة مستقلة تتضمن الأنماط.

لماذا لا تظهر صورة ذات مسار نسبي؟

لأن العارض لا يملك وصولًا إلى المجلدات الأخرى في المستودع: مسار مثل ./docs/logo.png موجود فقط على قرصك أو على GitHub. أما الصور ذات العنوان الكامل التي تبدأ بـ https:// فتُعرض دون مشكلة.