آموزش جامع Marked.js

📚معرفی و شروع سریع

Marked.js یک رشتهٔ Markdown را می‌گیرد و خروجی HTML برمی‌گرداند. تنها کاری که لازم است صدا زدن marked.parse() است.

<!-- بارگذاری کتابخانه -->
<script src="marked.min.js"></script>

<div id="out"></div>
<script>
const md = '# سلام دنیا\n\nاین **Markdown** است.';
document.getElementById('out').innerHTML = marked.parse(md);
</script>

✎ویرایشگر زنده

متن سمت راست را تغییر دهید تا خروجی HTML بلافاصله سمت چپ رندر شود — قلب اکثر ویرایشگرهای Markdown همین است.

const input  = document.getElementById('editor');
const output = document.getElementById('preview');

input.addEventListener('input', () => {
  output.innerHTML = marked.parse(input.value);
});

📄نحو Markdown

مرجع سریع پرکاربردترین نحوها. سمت راست کد Markdown، سمت چپ خروجی رندرشده.

⚙گزینه‌ها (options)

با marked.use() یا پاس دادن آبجکت گزینه به parse، رفتار را تنظیم کنید.

// تنظیم سراسری
marked.use({
  gfm:        true,    // GitHub Flavored Markdown (پیش‌فرض)
  breaks:     true,    // تک خط جدید = <br>
  pedantic:   false    // سخت‌گیری به نسخهٔ اصلی markdown.pl
});

// یا فقط برای یک فراخوانی
marked.parse(md, { breaks: true });

📊GFM و جدول

با gfm:true (پیش‌فرض) امکاناتی مثل جدول، چک‌لیست، خط‌خورده و auto-link فعال می‌شوند.

// جدول GFM
| نام   | نقش       | امتیاز |
|-------|-----------|:------:|
| علی   | فرانت‌اند  |   ۹۵   |
| سارا  | بک‌اند     |   ۹۲   |

// چک‌لیست
- [x] انجام شد
- [ ] در حال انجام

🔗parseInline

برای رشته‌های کوتاه که نمی‌خواهید داخل <p> پیچیده شوند (مثل عنوان یا برچسب)، از parseInline استفاده کنید.

marked.parse('**سلام**');
// <p><strong>سلام</strong></p>

marked.parseInline('**سلام**');
// <strong>سلام</strong>   ← بدون <p>

🎨Renderer سفارشی

با override کردن متدهای renderer، خروجی HTML هر عنصر را کنترل کنید — مثلاً افزودن کلاس به لینک‌ها یا target="_blank".

marked.use({
  renderer: {
    link({ href, title, text }) {
      return `<a href="${href}" target="_blank" ` +
             `rel="noopener" class="ext">${text}</a>`;
    },
    heading({ text, depth }) {
      return `<h${depth} class="md-h">${text}</h${depth}>`;
    }
  }
});

⚡ترکیب با Highlight.js

برای رنگ‌آمیزی بلوک‌های کد داخل Markdown، Marked را با Highlight.js ترکیب کنید.

// بعد از بارگذاری هر دو کتابخانه
marked.use({
  renderer: {
    code({ text, lang }) {
      const valid = hljs.getLanguage(lang) ? lang : 'plaintext';
      const html = hljs.highlight(text, { language: valid }).value;
      return `<pre><code class="hljs">${html}</code></pre>`;
    }
  }
});

🔐امنیت و XSS

Marked به‌صورت پیش‌فرض خروجی را پاک‌سازی (sanitize) نمی‌کند. اگر Markdown از کاربر می‌آید، حتماً خروجی را با ابزاری مثل DOMPurify پاک کنید.

// خطرناک — ورودی کاربر بدون پاک‌سازی
out.innerHTML = marked.parse(userInput);  // ❌ خطر XSS

// امن — با DOMPurify
const dirty = marked.parse(userInput);
out.innerHTML = DOMPurify.sanitize(dirty);    // ✅

🔥الگوهای رایج

رندر فایل README از سرور

const res = await fetch('/README.md');
const md  = await res.text();
document.getElementById('doc').innerHTML =
  DOMPurify.sanitize(marked.parse(md));

بخش نظرات با Markdown

// کاربر Markdown می‌نویسد، شما امن رندر می‌کنید
function renderComment(text) {
  marked.use({ breaks: true });   // Enter = خط جدید
  return DOMPurify.sanitize(marked.parse(text));
}

📄 چیت‌شیت API

🚀زمین بازی کد (Playground)

Markdown بنویس و خروجی HTML را زنده ببین. در مثال اول داخل کادر تایپ کن تا لحظه‌ای رندر شود. نسخهٔ ۱۲.۰.۲ آفلاین بارگذاری می‌شود.