قالب‌های فایل
Markdown چیست؟ نحو، CommonMark و GFM
Markdown یک زبان نشانه‌گذاری سبک است که با چند نماد ساده، عنوان و فهرست و پیوند را به متن ساده اضافه میکند. تاریخچه، استانداردها و آنچه در تبدیل فایل‌های MD به Word یا PDF حفظ می‌شود را بررسی می‌کنیم.
نویسنده: Hemen Dönüştür Editör Ekibiتاریخ انتشار: 8 دقیقه مطالعه
فایل README یک پروژهٔ نرم‌افزاری، فهرست‌های عنوان‌دار در یک برنامهٔ یادداشت‌برداری یا واژه‌هایی که در یک پیام‌رسان با ستاره پررنگ می‌کنید را در نظر بگیرید. پشت همهٔ این‌ها یک ایده است: Markdown. Markdown یک زبان نشانه‌گذاری سبک است که اجازه می‌دهد با افزودن چند نماد ساده به متن ساده، عنوان، فهرست، پیوند و جدول تعریف کنید. فایل در هر ویرایشگر متنی خوانا می‌ماند، اما هر وقت لازم باشد می‌توان آن را به یک صفحهٔ HTML تمیز، سند Word یا PDF تبدیل کرد. این مقاله توضیح می‌دهد Markdown چگونه پدید آمد، نحو اصلی‌اش چیست، CommonMark و GitHub Flavored Markdown چه تفاوتی دارند و هنگام تبدیل فایل‌های MD به چه نکاتی باید توجه کرد.
Markdown چیست؟
Markdown هم مجموعه‌ای از قراردادهای نوشتاری است و هم نام رایج ابزارهایی که متن نوشته‌شده با این قراردادها را به HTML تبدیل می‌کنند. فایل‌ها معمولاً با پسوند .md یا .markdown ذخیره می‌شوند. به گفتهٔ سازنده‌اش، جان گروبر (John Gruber)، مهم‌ترین هدف طراحی، خوانایی است: یک سند Markdown باید بتواند همان‌طور که هست، به صورت متن ساده منتشر شود، بی‌آنکه به نظر برسد با تگ یا دستورهای قالب‌بندی نشانه‌گذاری شده است. جایی که HTML به <strong>important</strong> نیاز دارد، Markdown از **important** استفاده میکند و حتی نسخهٔ خام هم طبیعی خوانده می‌شود.
تاریخچهٔ کوتاه
جان گروبر Markdown را در سال 2004 ساخت و آرون شوارتز (Aaron Swartz) به‌عنوان هم‌فکر در سنجیدن ایده‌هایش همراهی کرد. این نحو از قراردادهای ایمیل متن ساده (ستاره برای تأکید، خط تیره برای فهرست) و زبان‌های نشانه‌گذاری پیشین مانند setext و Textile الهام گرفت. نسخهٔ 1.0.1 از Markdown.pl، اسکریپت Perl که گروبر در سایت Daring Fireball منتشر کرد، تاریخ 17 دسامبر 2004 را دارد.
با این حال توصیف گروبر بیشتر توضیح با مثال بود تا یک مشخصهٔ رسمی. موارد مبهم (فهرست‌های تودرتو، بلوک‌های کد تورفته، آمیختن با HTML) باعث شد هر پیاده‌سازی انتخاب‌های خودش را داشته باشد و یک متن واحد در ابزارهای مختلف خروجی‌های متفاوتی بدهد. دو پاسخ مهم به این وضع داده شد:
- CommonMark (2014): مشخصه‌ای به رهبری جان مک‌فارلین (John MacFarlane) که Markdown را بدون ابهام تعریف میکند و با صدها مثال آن را آزمون‌پذیر می‌سازد. نخستین نسخه‌ها در پاییز 2014 منتشر شدند؛ نسخهٔ فعلی 0.31.2 با تاریخ 28 ژانویهٔ 2024 است. این مشخصه هنوز 1.0 اعلام نشده است.
- GitHub Flavored Markdown (GFM، 2017): مشخصهٔ رسمی GitHub که بر پایهٔ CommonMark ساخته شده است. افزونههایی مانند جدول، فهرست کار (task list)، خطخورده، پیوند خودکار گسترده و، برای امنیت، فیلتر کردن برخی تگ‌های خام HTML را اضافه میکند. آخرین مشخصهٔ منتشرشده 0.29-gfm با تاریخ 6 آوریل 2019 است.
Markdown در زیرساخت اینترنت هم به رسمیت شناخته شد: RFC 7763 که در مارس 2016 منتشر شد، نوع رسانهٔ (MIME type) text/markdown را همراه با پارامتر اختیاری variant ثبت کرد که نشان می‌دهد نویسنده کدام گونهٔ Markdown را در نظر داشته است.
گونه‌های اصلی Markdown
جز CommonMark و GFM، گونه‌های پرکاربرد دیگری هم وجود دارند. RFC 7764 که همراه با RFC 7763 منتشر شد، چند مورد از آن‌ها را ثبت کرد و راهنمایی‌هایی برای استفاده ارائه داد:
- Markdown Extra: افزونه‌ای قدیمی که پانویس، فهرست تعریف و جدول را اضافه کرد.
- MultiMarkdown: گونه‌ای برای نگارش دانشگاهی، با فراداده، ارجاع و ارجاع متقابل.
- Pandoc Markdown: گونه‌ای که مبدل Pandoc به کار می‌برد، با افزونه‌های فراوان برای نوشتن کتاب و مقاله.
یک قاعدهٔ کاربردی: اگر سندتان فقط از عنوان، فهرست، پیوند، کد و جدول ساده استفاده میکند، تقریباً همه‌جا یکسان دیده می‌شود. اگر به پانویس، فهرست تعریف یا انواع خاص بلوک تکیه دارید، بررسی کنید محیط مقصد از کدام گونه پشتیبانی میکند.
نحو اصلی
بخشی از Markdown که هر روز لازم دارید چند دقیقه‌ای یاد گرفته می‌شود:
# Level one heading
## Level two heading
This paragraph has **bold**, *italic* and `code`.
- Bulleted list
- Second item
- Indented sub-item
1. Numbered list
2. Second step
[Link text](https://example.com)
> Blockquote
```
Multi-line code block
```جدول‌ها و فهرست‌های کار که GFM اضافه کرده چنین شکلی دارند:
| Format | Extension |
|--------|-----------|
| Markdown | .md |
| Plain text | .txt |
- [x] Write the draft
- [ ] Review itپاراگراف‌ها با خط خالی از هم جدا می‌شوند. در بیشتر پیاده‌سازی‌ها یک شکست خط تنها، بخشی از همان پاراگراف به شمار می‌آید؛ برای شکستن اجباری خط، انتهای آن را با دو فاصله تمام کنید. میتوانید مستقیماً درون Markdown هم HTML بنویسید. CommonMark این را مجاز می‌داند، هرچند محیط‌هایی مانند GFM برخی تگ‌ها را برای امنیت مسدود می‌کنند.
Markdown کجا به کار می‌رود؟
- توسعهٔ نرم‌افزار: READMEها، تغییرنامه‌ها (changelog) و راهنماهای مشارکت، به‌علاوهٔ issueها و نظرهای بازبینی کد در پلتفرم‌هایی مانند GitHub و GitLab.
- مستندات فنی: سازنده‌های سایت ایستا که از فایل‌های Markdown وب‌سایت می‌سازند.
- یادداشت‌برداری: بسیاری از برنامه‌های یادداشت، یادداشت‌ها را به صورت Markdown ذخیره یا خروجی می‌کنند.
- پلتفرم‌های گفت‌وگو و انجمن: پلتفرم‌هایی مانند Reddit و Discord از گونه‌هایی از Markdown استفاده می‌کنند.
- نگارش و نشر: تولید HTML، PDF، DOCX و EPUB از یک منبع Markdown با ابزارهایی مانند Pandoc.
- ابزارهای هوش مصنوعی: دستیارهای گفت‌وگومحور هوش مصنوعی اغلب پاسخ‌هایشان را با Markdown قالب‌بندی می‌کنند.
نقاط قوت و ضعف
| نقاط قوت | نقاط ضعف |
|---|---|
| حتی به شکل خام هم خواناست | گونه‌ها رفتار متفاوتی دارند |
| متن ساده: کم‌حجم، قابل‌حمل، سازگار با کنترل نسخه | قلم، رنگ و صفحه‌آرایی ندارد |
| به‌راحتی به HTML، PDF و Word تبدیل می‌شود | جدول پیچیده (سلولهای ادغامشده) ندارد |
| در چند دقیقه یاد گرفته می‌شود | تصاویر در فایل‌های جداگانه‌اند |
| به هیچ برنامه‌ای وابسته نیست | اشتباه در فاصله و تورفتگی خروجی را تغییر می‌دهد |
چه برنامه‌هایی Markdown را باز می‌کنند؟
چون Markdown متن ساده است، در هر ویرایشگر متنی، از جمله Notepad و TextEdit، باز می‌شود. برای پیشنمایش قالببندیشده میتوانید از پیشنمایش داخلی Markdown در Visual Studio Code یا ویرایشگرهای اختصاصی مانند Obsidian و Typora استفاده کنید. GitHub و GitLab فایل‌های .md موجود در مخزن‌ها را خودکار رندر می‌کنند. اما Word فایل Markdown را به صورت متن قالببندیشده باز نمی‌کند، پس ابتدا باید فایل را تبدیل کنید.
مشکلات رایج و راه‌حل آن‌ها
یک فهرست یا عنوان رندر نمی‌شود
CommonMark پس از نشانهٔ عنوان یک فاصله لازم دارد: ## Heading، نه ##Heading. فهرستی هم که بعد از یک پاراگراف می‌آید اغلب برای رندر درست به یک خط خالی در میان نیاز دارد.
خط‌ها به هم می‌چسبند
یک شکست خط تنها پاراگراف را جدا نمی‌کند. برای پاراگراف جدید یک خط خالی بگذارید یا برای شکستن خط درون پاراگراف، انتهای خط را با دو فاصله تمام کنید.
جدولی در یک پلتفرم کار میکند و در دیگری نه
جدول‌ها جزو Markdown اصلی گروبر یا هستهٔ CommonMark نیستند و از افزونههایی مانند GFM می‌آیند. بررسی کنید پلتفرم مقصد از کدام گونه پشتیبانی میکند.
پاراگرافی که با عدد شروع می‌شود به فهرست شماره‌دار تبدیل می‌شود
خطی مانند «2024. was a busy year» با رقم و نقطه شروع می‌شود و ممکن است فهرست تفسیر شود. برای جلوگیری، نقطه را با بک‌اسلش گریز دهید (2024\.).
نکته‌هایی برای تبدیل فایل‌های Markdown
در مبدل ما، فایل‌های Markdown روی سرور ما آپلود می‌شوند و ظرف 30 دقیقه حذف می‌شوند. برای خواندن آن‌ها از کتابخانهٔ Markdig با CommonMark و افزونه‌های سبک GitHub (جدول، فهرست کار، پانویس، پیوند خودکار) استفاده می‌کنیم.
- تبدیل Markdown به PDF و تبدیل Markdown به Word عنوان‌ها، فهرست‌ها، بلوک‌های کد، نقل‌قول‌ها و جدولهای کادردار را حفظ می‌کنند. کادرهای انتخاب فهرست کار به نویسه‌های ☑ و ☐ تبدیل می‌شوند تا در Word و PDF دیده شوند. متن به‌طور پیش‌فرض با قلم سریف 12 pt و بلوک‌های کد با قلم تک‌فاصله چیده می‌شوند.
- تبدیل Markdown به HTML یک README را به صفحهٔ وب خودبسنده‌ای با رمزگذاری اعلام‌شده تبدیل میکند.
- در جهت عکس، تبدیل Word به Markdown، تبدیل HTML به Markdown و تبدیل PDF به Markdown خروجی Markdown سازگار با GitHub می‌دهند: عنوان‌ها، متن پررنگ و کج، فهرست‌ها، جدول‌ها، پیوندها، بلوک‌های کد و نقل‌قول‌ها حفظ می‌شوند؛ قلم‌ها، رنگ‌ها و صفحه‌آرایی کنار گذاشته می‌شوند. در جدولهای بدون ردیف سرآیند، ردیف نخست سرآیند می‌شود، چون جدولهای GFM به آن نیاز دارند. پاراگراف‌های ساده‌ای که با عدد شروع می‌شوند، مانند «1. بند»، گریز داده می‌شوند تا تصادفاً به فهرست تبدیل نشوند. فایل با UTF-8 بدون BOM ذخیره می‌شود.
پرسش‌های متداول
چطور فایل MD را باز کنم؟
هر ویرایشگر متنی آن را باز میکند. برای دیدن نسخهٔ قالببندیشده از پیشنمایش Visual Studio Code یا یک ویرایشگر Markdown استفاده کنید؛ اگر میخواهید آن را در Word بخوانید، به DOCX تبدیلش کنید.
تفاوت CommonMark و GitHub Flavored Markdown چیست؟
CommonMark نحو اصلی Markdown را با قواعد دقیق تعریف میکند. GFM ابرمجموعهای است که افزونههایی مانند جدول، فهرست کار، خطخورده و پیوند خودکار گسترده را بر پایهٔ CommonMark اضافه میکند.
آیا میتوانم در Markdown جدول بسازم؟
بله، با افزونههایی مانند GFM میتوانید با خط عمودی و خط تیره جدولهای ساده بنویسید. برای ساختارهای پیچیده مانند سلولهای ادغامشده، از جدول HTML استفاده کنید یا سند را در Word آماده کنید.
تفاوت Markdown و HTML چیست؟
Markdown فرمت نوشتاری سادهتری است که برای تبدیل شدن به HTML طراحی شده. نمیتواند هر چیزی را که HTML بیان میکند بیان کند، اما شکل خامش بسیار خواناتر است. هر وقت لازم باشد همچنان میتوانید درون Markdown، HTML بنویسید.
آیا Markdown استاندارد رسمی دارد؟
توصیف اصلی گروبر یک مشخصهٔ رسمی نیست. پذیرفتهشدهترین تعریف دقیق امروز CommonMark است و نوع رسانهٔ text/markdown در مارس 2016 با RFC 7763 ثبت شد.
