مارک داون چیست؟ آموزش زبان Markdown با مثال‌های کاربردی

وقتی مشغول مستندسازی یک پروژه، گزارش تحلیل داده یا حتی نوشتن یک یادداشت هستید، درگیر شدن با تگ‌های شلوغ HTML یا نوارابزارهای سنگین نرم‌افزارهای واژه‌پرداز، تمرکز نوشتن را از بین می‌برد. مارک داون (Markdown) یک زبان نشانه‌گذاری سبک است که به شما امکان می‌دهد با استفاده از نشانه‌ها و کاراکترهای ساده کیبورد (مانند #، * و [])، متن‌های ساده و خام را بدون نیاز به ماوس یا ابزارهای گرافیکی پیچیده، ساختاربندی و به خروجی‌های استانداردی مثل HTML تبدیل کنید.

حالا در یک نگاه ببینیم مارک داون چیست: در این شیوه، فایل نهایی شما در قالب متن ساده (Plain Text) ذخیره می‌شود که حتی قبل‌از تبدیل به خروجی نهایی، کاملاً خوانا و تمیز است. این ساختار سبک، فرایند تولید محتوا، ویرایش اسناد در گیت‌هاب و یادداشت‌برداری در محیط‌های توسعه را چندین برابر سریع‌تر می‌کند.

در این مقاله، ابتدا سازوکار فنی زبان Markdown و استانداردهای آن را بررسی می‌کنیم، سپس با یک جدول تقلب کاربردی، تمام سینتکس‌های پرکاربرد را یاد می‌گیریم. در ادامه، راهکارهای حل چالش مارک داون فارسی (مدیریت راست‌به‌چپ یا RTL)، تفاوت ساختاری آن با HTML و نحوه استفاده عملی از Markdown در نوت‌بوک‌های JupyterLab را پیاده‌سازی خواهیم کرد.

زبان Markdown چگونه کار می‌کند؟

برای اینکه بدانیم مارک داون چیست و چگونه چند کاراکتر ساده روی کیبورد را به یک صفحه وب ساختاریافته تبدیل می‌کند، نیازی به فهم مفاهیم پیچیده کامپایلرها نداریم. مارک‌داون بر پایه یک اصل مهندسی بسیار ساده اما هوشمندانه بناشده است: جداسازی محتوا از لایه نمایش با کمترین میزان شلوغی بصری

Markdown زبان برنامه‌نویسی نیست

یکی از اشتباهات رایج افراد این است که مارک‌داون را یک زبان برنامه‌نویسی می‌دانند. در واقع، زبان Markdown یک زبان نشانه‌گذاری سبک (Lightweight Markup Language) است. تفاوت این دو مفهوم در هدف آن‌ها است:

• زبان برنامه‌نویسی (مانند پایتون، C++ یا جاوااسکریپت): شامل منطق اجرایی، شرط‌ها، حلقه‌ها، متغیرها و توابع است و وظیفه پردازش و محاسبه را برعهده دارد.
• زبان نشانه‌گذاری (مانند Markdown یا HTML): هیچ منطق محاسباتی ندارد؛ فقط وظیفه دارد به نرم‌افزار بفهماند که کدام بخش از متن یک تیتر است، کدام کلمه باید برجسته (Bold) شود و کدام بخش یک لیست یا بلوک کد است.

فایل Markdown متنی کاملاً خام است که معمولاً با پسوند ‎.md یا ‎.markdown ذخیره می‌شود. ویژگی کلیدی این فایل‌ها در این است که برخلاف فایل‌های نرم‌افزارهایی مثل Microsoft Word (با پسوند ‎.docx) که حاوی داده‌های باینری و ساختارهای فشرده غیرقابل‌خواندن هستند، فایل‌های ‎.md را می‌توانید در ساده‌ترین ویرایشگرهای متنی (حتی Notepad ویندوز یا Nano در ترمینال لینوکس) باز کنید و بدون هیچ ابزار جانبی، متن را کاملاً تمیز و روان بخوانید.

نحوه تبدیل Markdown به HTML یا خروجی قابل‌نمایش

(عنوان اینفوگرافیک: فرایند تبدیل Markdown به خروجی
گام ۱: متن خام در فایل md —> گام ۲: تحلیل متن توسط پارسر مارک‌داون —> گام ۳: تولید درخت تگ‌های HTML —> گام ۴: رندر و نمایش گرافیکی در مرورگر یا ادیتور)

فرایند تبدیل سینتکس مارک‌داون به خروجی نهایی، طی یک پایپ‌لاین سه‌مرحله‌ای انجام می‌گیرد:

[فایل متن خام md] ── (موتور پارسر) ──> [درخت نحوی / کد HTML] ── (موتور رندر) ──> [خروجی بصری و نهایی]

۱- خواندن متن خام (Parsing): هنگامی که شما متنی مانند ## تیتر دوم یا **متن مهم** را ذخیره می‌کنید، موتور پردازشگر مارک‌داون (Markdown Parser) متن را خط‌به‌خط اسکن کرده و علائم نشانه‌گذاری را شناسایی می‌کند.

۲- تبدیل به تگ‌های متناظر: پارسر این نشانه‌ها را به برچسب‌های استاندارد زبان HTML تبدیل می‌کند. برای مثال:

• علامت # به تگ <h1>…</h1> تبدیل می‌شود.
• دو علامت ستاره **متن** به تگ <strong>متن</strong> ترجمه می‌شود.
• ساختار [عنوان](لینک) به تگ <a href=”…”>عنوان</a> تغییر می‌یابد.

۳- رندر و نمایش نهایی: مرورگر وب، نرم‌افزار مدیریت مستندات، یا ویرایشگر شما، کد HTML حاصل را می‌خواند و المان‌های بصری را با فونت و استایل تعریف‌شده به کاربر نشان می‌دهد.

عکس طراحانه:
عنوان: مثالی از ورودی مارک داون و خروجی توسط سیستم
متن‌ها:
<عنوان: ورودی شما در فایل Markdown >
# تحلیل عملکرد سرور
این یک **گزارش فوری** است.
<عنوان: خروجی تولید شده توسط پارسر برای سیستم>
<h1>تحلیل عملکرد سرور</h1>
<p>این یک <strong>گزارش فوری</strong> است.</p>

تاریخچه کوتاه و فلسفه ابداع Markdown

در سال ۲۰۰۴، جان گروبر (John Gruber) با همکاری آرون شوارتز (Aaron Swartz) زبان Markdown را ابداع کردند. مسئله اصلی در آن زمان این بود که توسعه‌دهندگان و وبلاگ‌نویسان برای انتشار یک متن ساده در وب مجبور بودند حجم زیادی از تگ‌های تو‌در‌توی HTML را به‌صورت دستی تایپ کنند؛ کاری که خوانایی متن خام را در حین ویرایش از بین می‌برد و سرعت نوشتن را کاهش می‌داد.

فلسفه طراحی Markdown الهام‌گرفتن از نحوه قالب‌بندی ایمیل‌های متنی ساده در دهه‌های قبل بود؛ جایی‌که افراد برای تأکید روی یک کلمه آن را بین دو ستاره قرار می‌دادند (*مهم*) یا برای نقل‌قول از علامت > استفاده می‌کردند. گروبر سینتکسی طراحی کرد که متن خام حتی بدون تبدیل‌شدن به صفحه وب، برای چشم انسان کاملاً خوانا و قابل‌درک باشد.

CommonMark چیست و چرا تفاوت ابزارها اهمیت دارد؟

در تعریف اولیه جان گروبر، برخی از جزئیات فنی و رفتارهای مرزی مسکوت مانده بودند؛ مثلاً اینکه اگر کاربر ۴ فاصله قبل‌از یک لیست بگذارد یا چند علامت را باهم ترکیب کند چه خروجی باید تولید شود؟ این ابهامات باعث شد توسعه‌دهندگان مختلف مفسرهای اختصاصی خود را بسازند که منجر به پیدایش گونه‌ها یا لهجه‌های مختلف مارک‌داون (Markdown Flavors) شد.

این تشتت باعث می‌شد یک فایل .md در گیت‌هاب درست نمایش داده شود، اما در یک نرم‌افزار دیگر دچار به‌هم‌ریختگی شود.

• پیدایش CommonMark: در سال ۲۰۱۴، گروهی از مهندسان ارشد پروژه‌های بزرگ (از جمله GitHub، Stack Overflow و Reddit) استانداردی مشخص، بدون ابهام و سخت‌گیرانه به نام CommonMark را تدوین کردند تا رفتار پارسرها در تمام پلتفرم‌ها یک‌دست شود.
• اکستنشن GFM: گیت‌هاب استاندارد CommonMark را پایه قرار داد و قابلیت‌های پرکاربردی مثل جدول‌ها، چک‌لیست کارها، خط‌زدن روی متن و هایلایت سینتکس کدها را به آن اضافه کرد که امروزه به محبوب‌ترین استاندارد مارک‌داون در میان برنامه‌نویسان و تحلیل‌گران داده تبدیل شده است.

چرا از مارک‌داون استفاده می‌کنیم؟

پذیرش گسترده یک ابزار معمولاً دلیلی فراتر از تبلیغات دارد؛ در مورد مارک‌داون، دلیل این استقبال فراگیر، حل یک نیاز قدیمی یعنی ساده‌سازی نگارش و مدیریت اسناد متنی است. وقتی متوجه می‌شویم مزیت‌های اصلی مارک داون چیست و چه باری را از دوش نویسنده برمی‌دارد، بازگشت به روش‌های سنتی قالب‌بندی متن بسیار دشوار خواهد بود.

(عنوان اینفوگرافیک: ۴ مزیت اصلی زبان Markdown
خوانایی بدون پیش‌پردازش
نگارش سریع بدون نیاز به ماوس
سازگاری کامل با سیستم‌های کنترل نسخه
ماندگاری داده بدون وابستگی به نرم‌افزار خاصی)

خوانایی فایل حتی پیش‌از تبدیل به خروجی

بزرگ‌ترین برگ برنده مارک‌داون، مفهوم خوانایی برای انسان (Human-readable) در حالت متن خام است. در نرم‌افزاری مانند Microsoft Word، محتوای سند درون لایه‌ای از متادیتای باینری پنهان است و بدون اجرای خود برنامه باز نمی‌شود. در HTML نیز تراکم تگ‌های باز و بسته، تمرکز روی متن را دشوار می‌کند. اما فایل Markdown حتی اگر درون یک ویرایشگر ساده بدون هیچ قابلیت گرافیکی باز شود، ساختار خود را به وضوح نشان می‌دهد.

مثال خوانایی متن در مارک‌داون

# راهنمای استقرار پروژه

برای راه‌اندازی سرویس، ابتدا وابستگی‌ها را نصب کرده و سپس دستور زیر را اجرا کنید:

* مرحله ۱: بررسی متغیرهای محیطی

* مرحله ۲: اجرای فایل اجرایی

همان متن در قالب تگ‌های شلوغ HTML

<h1>راهنمای استقرار پروژه</h1>
<p>برای راه‌اندازی سرویس، ابتدا وابستگی‌ها را نصب کرده و سپس دستور زیر را اجرا کنید:</p>
<ul>
  <li>مرحله ۱: بررسی متغیرهای محیطی</li>
  <li>مرحله ۲: اجرای فایل اجرایی</li>
</ul>

سرعت نوشتن و نیاز کمتر به تگ‌های HTML

هنگام نوشتن متن‌های تخصصی، جابه‌جا کردن دست بین کیبورد و ماوس برای هایلایت کردن کلمات، باز کردن منوهای کشویی یا انتخاب فونت، ریتم فکری نویسنده را متوقف می‌کند.

• تمرکز روی محتوا به‌جای استایل: با سینتکس Markdown دست شما همیشه روی کلیدهای کیبورد می‌ماند؛ یک کاراکتر # در ابتدای خط تیتر می‌سازد و دو ستاره ** متن را پررنگ می‌کند.
• بی‌نیازی از بستن تگ‌ها: در HTML فراموش کردن یک تگ پایانی می‌تواند کل چیدمان صفحه را به‌هم بریزد، اما نشانه‌های مارک‌داون ساختاری بسته و ایمن دارند و خطای انسانی را به‌حداقل می‌رسانند.

سازگاری با ابزارهای توسعه، مستندسازی و یادداشت‌برداری

متن ساده به این معنا است که فایل‌های ‎.md مستقل از سیستم‌عامل و نرم‌افزارها هستند. این ویژگی سه برتری فنی مهم ایجاد می‌کند:

1. همگام‌سازی بی‌نقص با گیت: مقایسه تغییرات (Git Diff) در فایل‌های مارک‌داون خط‌به‌خط و کاملاً شفاف است؛ درحالی‌که فایل‌های ورد یا پی‌دی‌اف در گیت صرفاً به‌عنوان یک فایل باینری غیرقابل مقایسه شناسایی می‌شوند.
2. پایداری در طول زمان: فایل متنی ساده ۲۰ سال بعد هم روی هر سیستمی بدون نیاز به لایسنس یا نسخه خاصی از یک برنامه باز خواهد شد.
3. انعطاف در تبدیل به فرمت‌های دیگر: با ابزارهای مبدل مانند Pandoc می‌توانید یک فایل Markdown را در چند ثانیه به PDF، HTML، EPUB، اسلاید ارائه یا مستندات وب تبدیل کنید.

محدودیت‌های Markdown

شاید بپرسید پس چرا این زبان جایگزین کامل HTML یا واژه‌پرداز نیست؟ باید گفت مارک‌داون برای ساختاردهی سریع متن ساخته شده است، نه طراحی گرافیکی پیچیده یا صفحه‌آرایی چاپ. شناخت نقاط مرزی این زبان مانع از استفاده نادرست آن می‌شود:

مهم‌ترین کاربردهای Markdown

دامنه نفوذ و کاربرد Markdown امروزه فراتر از یادداشت‌های شخصی است و تقریباً در تمام بخش‌های چرخه توسعه نرم‌افزار، تولید محتوای وب و پردازش داده‌ها دیده می‌شود.

عنوان اینفوگرافیک: کاربردهای Markdown
متن‌ها:
فایل README و مستندات پروژه در  Git/ تولید محتوا در CMSها / یادداشت‌برداری، ویکی و مدیریت دانش تیمی / پیام‌رسان‌ها و ابزارهای همکاری تیمی / مستندسازی تحلیل داده در Jupyter Notebook و JupyterLab

۱- فایل README و مستندات پروژه در GitHub/GitLab

اولین چیزی که هنگام بازکردن مخزن یک پروژه نرم‌افزاری در گیت‌هاب یا گیت‌لب دیده می‌شود، فایل README.md است. این فایل ویترین پروژه است و وظیفه دارد نحوه نصب، وابستگی‌ها، معماری سیستم و مجوزهای نرم‌افزار را توضیح دهد. پلتفرم‌های میزبانی کد به‌صورت خودکار این فایل را رندر می‌کنند و به‌عنوان صفحه اصلی مخزن نمایش می‌دهند.

۲- تولید محتوا در CMSها، وبلاگ‌ها و سایت‌های مستندات

بسیاری از سیستم‌های مدیریت محتوای مدرن (Headless CMS) و ژنراتورهای سایت ایستا (SSG) مانند Hugo، Docusaurus، MkDocs و Jekyll هسته اصلی محتوای خود را بر پایه مارک‌داون قرار داده‌اند. نویسندگان نیز می‌توانند مقالات خود را در قالب فایل‌های متنی بنویسند تا فریم‌ورک‌ها آن را به سایت‌های مستندات با سرعت بارگذاری فوق‌العاده تبدیل کنند.

۳- یادداشت‌برداری، ویکی و مدیریت دانش تیمی

ابزارهای نوین مدیریت دانش شخصی (PKM) و سازمانی مثل Obsidian، Logseq و Notion از مارک‌داون به‌عنوان ساختار پایه‌ای نوشتن استفاده می‌کنند. ذخیره یادداشت‌ها به شکل متن ساده به کاربران اجازه می‌دهد روابط بین مفاهیم، چک‌لیست کارهای روزمره و دایره‌المعارف‌های تخصصی تیم را بدون نگرانی از دست رفتن دسترسی در آینده پیاده‌سازی کنند.

۴- پیام‌رسان‌ها و ابزارهای همکاری تیمی

اکثر پیام‌رسان‌های حرفه‌ای و محیط‌های گفتگو مانند Slack، Discord، Mattermost و حتی تلگرام، زیرمجموعه‌ای از دستورات نشانه‌گذاری را برای فرمت‌بندی متن پیام‌ها پیاده‌سازی کرده‌اند. ارسال قطعه‌کدهای درون‌خطی با علامت بک‌تیک (`code`) یا برجسته‌کردن کلمات در چت‌های کاری از پرکاربردترین الگوهای روزمره این بخش است.

۵- مستندسازی تحلیل داده در Jupyter Notebook و JupyterLab

در محیط‌های تعاملی علم داده، نوشتن کد به تنهایی برای ارائه گزارش کافی نیست؛ تحلیل‌گر باید فرضیات اولیه، تفسیر آماری خروجی نمودارها و معادلات ریاضی را در کنار سلول‌های پایتون مستند کند. استفاده از Markdown در JupyterLab این امکان را می‌دهد که با تغییر نوع سلول، گزارش‌های تحلیلی شفاف، قابل بازتولید و ساختاریافته خلق شوند که در پروژه‌های تحقیقاتی و ارائه‌های فنی جایگزین فایل‌های گزارش جداگانه می‌شوند.

خلاصه‌ای از اکوسیستم ابزارهای مبتنی‌بر Markdown

آموزش سریع Markdown و جدول دستورات پرکاربرد

یادگیری نشانه‌گذاری متن بر خلاف یادگیری زبان‌های برنامه‌نویسی، تنها چند دقیقه زمان می‌برد. در این بخش از آموزش Markdown، تمام سینتکس‌های اصلی و استانداردهای پرکاربرد را به همراه مثال‌های عینی و خروجی نهایی آن‌ها مرور می‌کنیم.

جدول دستورات پایه در یک نگاه

تیترها (Headings)

برای ایجاد تیترها در سینتکس Markdown، از علامت هشتگ یا شارپ (#) استفاده می‌شود. تعداد علامت‌ها نشان‌دهنده سطح تیتر (از <h1> تا <h6>) است:

# تیتر سطح اول (معادل H1)
## تیتر سطح دوم (معادل H2)
### تیتر سطح سوم (معادل H3)
#### تیتر سطح چهارم (معادل H4)
##### تیتر سطح پنجم (معادل H5)
###### تیتر سطح ششم (معادل H6)

بولد، ایتالیک و خط‌خورده

برای تأکید روی کلمات و عبارات از ترکیب علامت‌های ستاره یا آندرلاین استفاده می‌کنیم:

• متن پررنگ (Bold): دو علامت ستاره یا دو آندرلاین در دو طرف کلمه: **این متن بسیار مهم است**
• متن کج (Italic): یک علامت ستاره یا یک آندرلاین در دو طرف کلمه: *این عبارت یک اصطلاح فنی است*
• ترکیب بولد و ایتالیک: سه علامت ستاره: ***نکته فوق‌العاده حیاتی***
• خط‌خوردگی: دو علامت مدک (Tilde) در دو طرف متن (طبق استاندارد GFM): ~~نسخه آزمایشی ۱.۰~~

فهرست‌های شماره‌دار و نشانه‌دار (Lists)

ساخت لیست‌ها بدون برداشتن دست از کیبورد انجام می‌شود:

۱. فهرست‌های نشانه‌دار (Unordered Lists)

با قرار دادن کاراکترهای -، * یا + در ابتدای خط می‌توانید لیست گلوله‌ای بسازید:

- زبان پایتون
- محیط ژوپیتر لب
  - افزونه Git
  - ابزار رسم نمودار
- پایگاه داده PostgreSQL

۲. فهرست‌های شماره‌دار (Ordered Lists)

با نوشتن عدد و نقطه ایجاد می‌شوند. جالب است بدانید اگر تمام آیتم‌ها را با 1. شروع کنید، موتور رندر به‌طور خودکار شماره‌ها را مرتب خواهد کرد:

1. دانلود مخزن پروژه
1. نصب وابستگی‌های پایتون
1. اجرای فایل سرور

لینک و تصویر

ساختار لینک در Markdown و درج تصویر شباهت بسیار زیادی به‌هم دارند، با این تفاوت که تصویر با یک علامت تعجب (!) آغاز می‌شود:

• ساختار لینک: [متن قابل کلیک](آدرس اینترنتی) –> برای بررسی زیرساخت، به [سایت ابر فردوسی](https://ferdowsi.cloud) مراجعه کنید.
• ساختار تصویر:  –> 

نقل‌قول و خط افقی

• باکس نقل‌قول (Blockquote): با افزودن علامت > در ابتدای سطر ساخته می‌شود و برای جلب توجه خواننده به یک نکته، هشدار یا نقل‌قول مستقیم کاربرد دارد: > پایداری داده‌ها و جداسازی محیط توسعه از دستگاه شخصی، ریسک توقف پروژه‌های تحلیلی را به صفر می‌رساند.
• خط افقی جداکننده (Horizontal Rule): تایپ ۳ علامت خط‌تیره متوالی (—) یا ۳ ستاره (***) در یک خط خالی، یک خط افقی در سراسر صفحه ایجاد می‌کند.

کد درون‌خطی و بلوک کد

برای توسعه‌دهندگان، مهندسان سیستم و تحلیل‌گران داده، درج اصولی کد در Markdown اهمیت بالایی دارد:

• کد درون‌خطی (Inline Code): قرار دادن دستورات کوتاه داخل یک جفت بک‌تیک (`). مثال: برای نصب پکیج، دستور `pip install jupyterlab` را در خط فرمان اجرا کنید.
• بلوک کد چندخطی (Code Block): استفاده از سه بک‌تیک در بالا و پایین کد همراه با مشخص کردن نام زبان برای فعال‌شدن برجسته‌سازی نحوی

جدول‌ها

ساخت جدول در Markdown با استفاده از علامت‌های لوله‌خط (|) برای ستون‌ها و خط‌تیره (-) برای جداسازی سطر عنوان انجام می‌شود:

| نام سرویس | نوع منبع پردازشی | وضعیت اتصال |
| :--- | :---: | ---: |
| سرور ژوپیتر لب | GPU اختصاصی | فعال |
| فضای ابری S3 | دیسک پرسرعت | متصل |

راهنمای چینش متن در جدول:

• :— چینش به چپ (مناسب کدهای انگلیسی و اعداد)
• :—: چینش به مرکز
• —: چینش به راست (مناسب متون فارسی)

چک‌لیست و تیک‌زدن کارها

برای پیگیری گام‌به‌گام مراحل استقرار یا وظایف تیم، می‌توانید از چک‌باکس‌های تعاملی استفاده کنید:

- [x] راه‌اندازی سرور ابری و پیکربندی اولیه
- [x] نصب پکیج‌های پایتون در محیط مجازی
- [ ] اجرای آزمایشی مدل یادگیری ماشین
- [ ] اتصال به مخزن گیت و انتشار نسخه پایدار

یک مثال واقعی از ساخت README ساده با Markdown

برای اینکه ببینیم تمام این نشانه‌ها در کنار هم چطور یک سند فنی را شکل می‌دهند، با هم یک فایل README.md استاندارد می‌سازیم. اگر برایتان سؤال است که نقش واقعی README چیست، باید گفت این فایل اولین شناسنامه پروژه شما در گیت‌هاب است که به توسعه‌دهندگان دیگر می‌گوید این پروژه چه می‌کند و چگونه باید اجرا شود.

کد کامل نمونه

متن خام زیر نمونه‌ای از یک سند معرفی پروژه پردازش داده است که می‌توانید در مخزن گیت خود قرار دهید:

# پلتفرم تحلیل بلادرنگ داده‌های مالی

این پروژه ابزاری متن‌باز برای استخراج، پاکسازی و مصورسازی شاخص‌های بازار مالی با استفاده از پایتون است.

---

## 📋 پیش‌نیازهای اجرا
پیش از راه‌اندازی اسکریپت، از نصب بودن پیش‌نیازهای زیر اطمینان حاصل کنید:
* پایتون نسخه ۳.۱۰ یا بالاتر
* دسترسی به اینترنت پایدار جهت دریافت دیتاست
* حساب فعال در سرویس پردازش ابری

## ⚙️ راهنمای نصب و راه‌اندازی
ابتدا مخزن را کلون کرده و پکیج‌ها را نصب کنید:

```bash
git clone [https://github.com/example/finance-analyzer.git](https://github.com/example/finance-analyzer.git)
cd finance-analyzer
pip install -r requirements.txt ```

نکات خوانایی سلسله‌مراتب تیتر و فاصله‌گذاری

برای اینکه اسناد فنی شما خوانایی بالایی داشته باشند و توسط موتورهای جستجو و ابزارهای تولید فهرست به درستی پردازش شوند، سه قاعده ساده را همیشه رعایت کنید:

1. حفظ سلسله‌مراتب تیترها: در کل سند فقط یک‌بار از تیتر سطح اول (`#`) به‌عنوان نام پروژه استفاده کنید. بخش‌های اصلی را با `##` و زیربخش‌ها را با `###` تفکیک کنید. هرگز از تیتر سطح ۲ مستقیماً به تیتر سطح ۴ پرش نکنید.
2. یک خط فاصله قبل و بعداز المان‌ها: همیشه بین پاراگراف‌ها، لیست‌ها، جداول و بلوک‌های کد، **یک خط خالی** بگذارید تا موتور پارسر بدون ابهام ساختار را تفکیک کند.
3. پرهیز از شلوغی بیش‌ازحد: استفاده هم‌زمان از بولد، ایتالیک و ایموجی در یک جمله کوتاه، تمرکز خواننده را بر هم می‌زند؛ از فرمت‌بندی فقط برای کلمات کلیدی و مقادیر متغیر استفاده کنید.

مارک داون فارسی؛ چالش‌ها و راه‌حل‌ها

یکی از پرتکرارترین چالش‌های توسعه‌دهندگان و نویسندگان ایرانی، مدیریت چیدمان راست‌به‌چپ (RTL) و نگارش متون فارسی در کنار واژه‌های انگلیسی یا قطعه‌کدها است. در حالت پیش‌فرض، استاندارد Markdown برای زبان‌های چپ‌به‌راست (LTR) طراحی شده و اگر قواعد ترکیب زبان‌ها را ندانید، پدیده‌هایی مثل پرش علائم نگارشی، به‌هم‌ریختگی لینک‌ها و وارونه شدن پرانتزها تجربه نوشتن را مشکل می‌کند. با شناخت سازوکار مفسرها، حل چالش‌های مارک داون فارسی کار بسیار ساده‌ای است.

(عنوان تصویر: مارک ‌داون پیش‌فرض VS مارک داون فارسی
توضیحات: در سمت چپ: متن خام فارسی همراه با کلمات انگلیسی که علائم نگارشی آن به‌هم ریخته است؛ در سمت راست: همان متن با اعمال تگ‌های راست‌به‌چپ و نمایش منظم و استاندارد)

آیا Markdown از فارسی پشتیبانی می‌کند؟

پاسخ کوتاه: بله، کاملاً. فایل‌های متنی مارک‌داون با انکودینگ جهانی UTF-8 ذخیره می‌شوند؛ بنابراین تمام کاراکترهای الفبای فارسی، اعراب‌ها، اعداد فارسی و نیم‌فاصله‌ها بدون هیچ مشکلی ذخیره و خوانده می‌شوند. مسئله اصلی در پشتیبانی از زبان فارسی نیست، بلکه در جهت نمایش متن (Directionality) است. استاندارد مرجع CommonMark نشانه مستقلی برای تعریف جهت صفحه یا پاراگراف ندارد و وظیفه تشخیص جهت متن (RTL یا LTR) را به موتور رندرکننده (مانند مرورگر، نرم‌افزار نوت‌برداری یا پلتفرم گیت‌هاب) واگذار می‌کند.

مدیریت متن راست‌به‌چپ در کنار کد و واژه‌های انگلیسی

وقتی در یک پاراگراف فارسی از کلمات انگلیسی یا متغیرهای برنامه‌نویسی استفاده می‌کنید، الگوریتم دوجهته یونیکد (BiDi Algorithm) ممکن است محل قرارگیری نقطه پایانی، پرانتزها یا کلمات لاتین را جابه‌جا نشان دهد.

برای مهار این اختلال، این ۳ اصل کاربردی را در ساختار متن رعایت کنید:

۱. قراردادن تمام واژگان انگلیسی در کد درون‌خطی

هر زمان که به نام یک تابع، دستور ترمینال یا پکیج انگلیسی اشاره می‌کنید، آن را داخل بک‌تیک (`…`) بگذارید. این کار مرز کلمه را برای موتور رندر مشخص کرده و مانع از شکست خط می‌شود.

۲. شروع نکردن پاراگراف با کلمات انگلیسی

اگر یک سطر را با یک واژه انگلیسی یا عدد شروع کنید، کل خط ممکن است چپ‌چین شود. خطوط را همیشه با حروف فارسی آغاز کنید.

۳. استفاده از نیم‌فاصله (ZWNJ)

برای پیشگیری از دو تکه شدن کلمات ترکیبی فارسی مثل «می‌شود» یا «دستور‌العمل‌ها»، از نیم‌فاصله استفاده کنید تا خط تداوم بصری خود را حفظ کند.

راهکار استفاده از HTML در Markdown؛ تگ dir=”rtl”

ازآنجاکه مارک‌داون تگ‌های خام HTML را مستقیماً از خود عبور می‌دهد، قطعی‌ترین راهکار برای پلتفرم‌هایی که متون فارسی را به‌صورت پیش‌فرض چپ‌چین می‌کنند (مانند برخی قالب‌های مستندسازی)، محصور کردن متن در تگ‌های HTML با صفت dir=”rtl” است:

<div dir="rtl">

## راهنمای کاربری سرویس ابری
برای اجرای اسکریپت پایتون، ابتدا متغیر `API_KEY` را در محیط سیستم ثبت کنید.
* مرحله اول: دریافت کلید اتصال
* مرحله دوم: اجرای سرویس

</div>

| عنوان ماژول | شناسه سیستم (ID) | عملکرد |
| ---: | :--- | :---: |
| مدیریت احراز هویت | `auth_core` | پایدار |

برای مطالعه مستندات به [بخش راهنمای API سرور](https://ferdowsi.cloud) مراجعه کنید.

<div dir="rtl">

# مستندات فنی و راهنمای پایگاه داده

این راهنما برای پیکربندی اولیه سرور و اتصال ایمن به سیستم طراحی شده است.

### پیش‌نیازهای اتصال
* نصب بسته `psycopg2` در محیط مجازی
* دریافت مجوز دسترسی از طریق پورت `5432`

| پارامتر اتصال | مقدار نمونه | توضیحات تکمیلی |
| ---: | :--- | ---: |
| میزبان پایگاه داده | `192.168.1.10` | آدرس IP شبکه داخلی |
| نام کاربری مجاز | `admin_user` | دسترسی سطح دسترسی کامل |

> **نکته امنیتی:** هرگز اطلاعات ورود را در فایل‌های عمومی بدون رمزنگاری ذخیره نکنید.

</div>