📘 Markdown و MDX چیست؟

Markdown یک زبان نشانه‌گذاری سبک است که به شما امکان می‌دهد با استفاده از علائم ساده، متنی ساختاریافته و خوانا بنویسید که به راحتی به HTML تبدیل می‌شود. این زبان برای نوشتن مستندات، فایل‌های README، وبلاگ‌ها و محتوای وب بسیار محبوب است.

MDX نسخهٔ توسعه‌یافتهٔ Markdown است که امکان استفاده از کامپوننت‌های JSX (مانند React) را درون فایل‌های مارک‌داون فراهم می‌کند. با MDX می‌توانید علاوه بر نوشتن متن، المان‌های تعاملی و پویا را نیز به محتوای خود اضافه کنید.

📌 سینتکس پایه Markdown

۱. عناوین (Headings)

با قرار دادن علامت # قبل از متن، عنوان ایجاد می‌شود. تعداد # نشان‌دهندهٔ سطح عنوان است (از h1 تا h6).

# عنوان سطح ۱
## عنوان سطح ۲
### عنوان سطح ۳
#### عنوان سطح ۴
##### عنوان سطح ۵
###### عنوان سطح ۶

۲. لیست‌ها

لیست نامرتب (bullet list):
از علامت -، * یا + استفاده کنید.

- آیتم اول
- آیتم دوم
  - زیر آیتم

لیست مرتب (numbered list):
با اعداد و نقطه.

1. مرحله اول
2. مرحله دوم
   1. زیر مرحله

۳. تأکید بر متن

• متن بولد (پررنگ): با دو ستاره **متن** یا دو زیرخط __متن__
• متن کج (ایتالیک): با یک ستاره *متن* یا یک زیرخط _متن_
• متن بولد و کج: با سه ستاره ***متن***

۴. کد (Code)

کد درون‌خطی (Inline): با قرار دادن بین دو علامت ` (بک‌تیک)
مثال: var x = 10;

بلوک کد (Code block): با سه بک‌تیک و مشخص کردن زبان (اختیاری)

|```javascript
function hello() {
  console.log("Hello World!");
}
|```

۵. نقل قول (Blockquote)

با علامت > در ابتدای خط.

> این یک نقل قول است.
> می‌تواند چند خطی باشد.

۶. لینک و تصویر

لینک: [متن لینک](آدرس)

تصویر: ![متن جایگزین](آدرس تصویر)

[مشاهده مستندات رسمی](https://www.markdownguide.org)
![لوگوی مارک‌داون](/thumbnails/md.png)

📌 سینتکس پیشرفته Markdown

جدول‌ها (Tables)

با استفاده از خط تیره --- و دو نقطه : برای تنظیم تراز ستون‌ها.

| ستون چپ‌چین | ستون وسط‌چین | ستون راست‌چین |
|:---|:---:|---:|
| مقدار ۱ | مقدار ۲ | مقدار ۳ |
| ردیف دوم | وسط | راست |

خط افقی (Horizontal Rule)

با سه خط تیره --- یا سه ستاره *** یا سه زیرخط ___.

فهرست وظایف (Task List)

- [x] کار انجام شده
- [ ] کار انجام نشده

زیرنویس (Footnote)

این یک جمله با زیرنویس است[^1].
[^1]: متن زیرنویس.

جداول با ادغام سلول (در Markdown خام ممکن نیست، اما در برخی پیاده‌سازی‌ها پشتیبانی می‌شود)

📌 MDX – ترکیب Markdown و JSX

MDX به شما اجازه می‌دهد تا در کنار متن مارک‌داون، از کامپوننت‌های React (یا هر فریم‌ورک مبتنی بر JSX) استفاده کنید. این یعنی می‌توانید دکمه‌ها، فرم‌ها، نمودارهای تعاملی و هر المان پویای دیگری را درون محتوای خود قرار دهید.

مثال فایل MDX:

import Button from './Button';

# عنوان مطلب

متن معمولی مارک‌داون...

<Button onClick={() => alert('سلام!')}>
  کلیک کن
</Button>

مزایای MDX:

• ترکیب محتوای ایستا و پویا در یک فایل
• قابلیت استفاده مجدد از کامپوننت‌ها در مقالات
• مناسب برای سیستم‌های طراحی، مستندات تعاملی و وبلاگ‌های پیشرفته

تفاوت اصلی Markdown و MDX

📌 رسم نمودار با Mermaid در Markdown

بسیاری از ویرایشگرهای مارک‌داون از Mermaid پشتیبانی می‌کنند تا بتوانید نمودارهای جریان، توالی، کلاس و ... را با کدنویسی ساده رسم کنید.

flowchart TD
    A[شروع] --> B{آیا شرط برقرار است؟}
    B -->|بله| C[انجام کار]
    C --> A
    B -->|خیر| D[پایان]

sequenceDiagram
    Alice->>John: سلام جان
    John-->>Alice: سلام الیس

🧩 نتیجه‌گیری

Markdown ابزاری ضروری برای هر نویسندهٔ محتوا، توسعه‌دهنده و مستندساز است. یادگیری سینتکس آن بسیار سریع و آسان بوده و با ابزارهای فراوانی سازگار است. اگر به دنبال تعامل بیشتر و استفاده از قدرت فریم‌ورک‌های frontend هستید، MDX انتخاب مناسبی خواهد بود.

از این راهنما می‌توانید به عنوان مرجع سریع برای نوشتن فایل‌های .md و .mdx استفاده کنید و با کدنویسی تمیز، محتوای حرفه‌ای تولید کنید.

نکته: برای آشنایی بیشتر با Mermaid و نمونه‌های بیشتر، به سایت رسمی Mermaid مراجعه کنید.

برچسب‌ها: Markdown, MDX, آموزش مارک‌داون, سینتکس, Mermaid, JSX, مستندسازی