مارک‌داون

نود Markdown چیست؟

نود Markdown دو عملیات اصلی دارد:

1. 1Markdown to HTML: تبدیل متن Markdown به HTML
2. 2HTML to Markdown: تبدیل HTML به Markdown

چرا Markdown مهم است؟

• سادگی: نوشتن فرمت‌دار بدون نیاز به HTML
• استاندارد: در GitHub, GitLab, Notion, Slack استفاده می‌شود
• خوانایی: متن Markdown حتی بدون Render خوانا است
• قابلیت تبدیل: به HTML, PDF, DOCX قابل تبدیل

عناصر Markdown:

• هدینگ: # تا ######
• Bold/Italic: bold و *italic*
• لیست: - یا 1. 2. 3.
• لینک: [text](url)
• تصویر: 
• **کد**: \inline\ و \\\block\\\
• جدول: | header | header |
• نقل‌قول: > quote

Flavors مختلف:

• CommonMark: استاندارد پایه
• GFM (GitHub Flavored): جداول، Task List، Strikethrough
• MDX: Markdown + JSX Components

موارد استفاده رایج

۱. ارسال پیام فرمت‌دار در Slack

تبدیل داده به Markdown Table > ارسال در Slack Channel. Slack از Markdown پشتیبانی می‌کند.

۲. ایمیل HTML از محتوای Markdown

نوشتن محتوا در Markdown > تبدیل به HTML > ارسال ایمیل با فرمت زیبا.

۳. مستندسازی خودکار

جمع‌آوری داده از API > ساخت گزارش Markdown > Push به GitHub Repository.

۴. تبدیل ایمیل به Markdown

دریافت ایمیل HTML > HTML to Markdown > ذخیره در Notion یا Obsidian.

۵. ساخت Release Notes

دریافت commit messages از GitHub > فرمت‌دهی Markdown > ایجاد GitHub Release.

۶. گزارش‌دهی در Teams/Discord

داده‌های فروش > Markdown Table > ارسال در Microsoft Teams یا Discord.

۷. تبدیل Blog Post

دریافت HTML از CMS > HTML to Markdown > ذخیره در فایل .md > Push به Git.

۸. ساخت README خودکار

اطلاعات پروژه از API > قالب Markdown > ساخت README.md خودکار.

۹. محتوای Notion

تبدیل داده به Markdown > ایجاد صفحه Notion با محتوای فرمت‌دار.

۱۰. خلاصه روزانه

جمع‌آوری اطلاعات > فرمت Markdown با هدینگ و لیست > ارسال به Telegram.

نکات و ترفندها

Markdown سریع

• Bold: text یا __text__
• *Italic*: *text* یا _text_
• ~~Strikethrough~~: ~~text~~
• Code: \code\
• [Link](url): [text](url)
• > Quote: > text

جدول Markdown

| ستون ۱ | ستون ۲ | ستون ۳ | |--------|--------|--------| | داده | داده | داده |

تراز: |:---|:---:|---:| (چپ، وسط، راست)

ترکیب با Slack

Slack از mrkdwn (نه استاندارد Markdown) استفاده می‌کند:

• Bold: *text* (نه text)
• Italic: _text_
• Code: \code\
• Link: <url|text>

ترکیب با ایمیل

1. 1محتوا را در Markdown بنویسید
2. 2Markdown to HTML تبدیل کنید
3. 3CSS inline اضافه کنید
4. 4با SMTP ارسال کنید

Task List (GFM)

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

فرمت Heading

• # H1 (عنوان اصلی)
• ## H2 (بخش)
• ### H3 (زیربخش)

ادغام با سایر نودها

• Slack: ارسال پیام Markdown
• Discord: پیام فرمت‌دار
• GitHub: Issue, Comment, Release
• Notion: صفحه با محتوای Markdown
• Email (SMTP): HTML از Markdown
• Telegram: پیام با ParseMode: Markdown

نکات Performance

• Markdown سبک‌تر از HTML است
• برای داده‌های بزرگ، بخش بخش تبدیل کنید
• Cache نتایج تبدیل
• از Markdown برای ذخیره‌سازی استفاده کنید (کم‌حجم‌تر)

محتوای فارسی

• Markdown استاندارد از RTL پشتیبانی نمی‌کند
• در HTML خروجی، dir="rtl" اضافه کنید
• فونت فارسی در CSS تنظیم کنید
• از Unicode برای اعداد فارسی استفاده کنید

عیب‌یابی

۱. جدول Markdown رندر نمی‌شود

مشکل: جدول به صورت متن ساده نمایش داده می‌شود راه‌حل: GFM فعال باشد. هر ردیف باید با | شروع و پایان یابد. ردیف جداکننده (---) بعد از هدر الزامی است.

۲. کاراکترهای خاص Escape نمی‌شوند

مشکل: کاراکترهای * _ # به صورت فرمت تفسیر می‌شوند راه‌حل: از بک‌اسلش برای Escape استفاده کنید: \* \_ \#

۳. تبدیل HTML ناقص است

مشکل: برخی عناصر HTML به Markdown تبدیل نمی‌شوند راه‌حل: عناصر پیچیده HTML (table با colspan, nested lists) ممکن است دقیق تبدیل نشوند. از Code نود برای پردازش پیچیده استفاده کنید.

۴. فرمت فارسی مشکل دارد

مشکل: متن فارسی RTL با Markdown درست نمایش داده نمی‌شود راه‌حل: از dir="rtl" در HTML خروجی استفاده کنید. برخی Markdown rendererها RTL را خودکار تشخیص می‌دهند.

۵. Code Block فرمت می‌شود

مشکل: کد داخل بلاک کد هم فرمت Markdown می‌خورد راه‌حل: از سه backtick با زبان مشخص استفاده کنید. فاصله‌گذاری صحیح رعایت شود.

۶. لینک‌ها شکسته هستند

مشکل: URLهای طولانی یا حاوی پرانتز مشکل دارند راه‌حل: URL را در <angle brackets> قرار دهید. پرانتزها را encode کنید.

۷. HTML خروجی Sanitize نشده

مشکل: HTML خروجی حاوی اسکریپت‌های مخرب راه‌حل: sanitize: true را فعال کنید. هرگز HTML کاربر را بدون Sanitize رندر نکنید.