كيف يعمل Markdown

فهم آلية عمل Markdown يساعدك على استثماره جيداً. يشرح هذا الفصل كيف يتحول نص Markdown إلى مستند منسّق وجميل.

سير العمل الأساسي

يمكن تلخيص سير العمل بالخطوات التالية:

ملف Markdown (.md) → مُحلِّل Markdown → مستند HTML → عرض المتصفح

1) كتابة ملف Markdown

اكتب ملف .md بأي محرر نصوص مستخدماً قواعد Markdown:

# مستندي

هذه فقرة **مهمة**.

## مثال على قائمة

- عنصر 1
- عنصر 2
- عنصر 3

2) معالجة مُحلِّل Markdown

يقرأ المُحلِّل الملف ويحوّل العناصر إلى HTML:

<h1>مستندي</h1>
<p>هذه فقرة <strong>مهمة</strong>.</p>
<h2>مثال على قائمة</h2>
<ul>
  <li>عنصر 1</li>
  <li>عنصر 2</li>
  <li>عنصر 3</li>
</ul>

3) عرض المتصفح

يُعرَض HTML الناتج في المتصفح كمستند منسّق.

آلية عمل المُحلِّل

التحليل المعجمي

يبدأ المُحلِّل بتحليل معجمي لتقسيم النص إلى رموز (tokens):

• # عنوان
• **text** غامق
• - item عنصر قائمة

التحليل النحوي وبناء AST

ثم تحليل نحوي وبناء شجرة بناء مجردة (AST):

وثيقة
├── عنوان (المستوى 1): "مستندي"
├── فقرة
│   ├── نص: "هذه"
│   ├── غامق: "فقرة مهمة"
│   └── نص: "."
├── عنوان (المستوى 2): "مثال على قائمة"
└── قائمة غير مرتبة
    ├── عنصر: "عنصر 1"
    ├── عنصر: "عنصر 2"
    └── عنصر: "عنصر 3"

توليد HTML

أخيراً تُجتاز الشجرة لتوليد HTML المناظر.

مُحلِّلات شائعة

CommonMark

• 标准规范 - 提供统一的 Markdown 解析标准
• 严格定义 - 消除不同实现之间的歧义
• 广泛支持 - 被多个解析器采用

GitHub Flavored Markdown (GFM)

مبني على CommonMark مع إضافات مثل:

• دعم الجداول
• الشطب
• قوائم المهام
• التعرّف التلقائي على الروابط
• إبراز الشيفرة في الكتل

محللات أخرى

المُحلِّل	اللغة	الميزات
marked	JavaScript	سريع وخفيف
markdown-it	JavaScript	قابل للإضافة وقابلية توسعة
Python-Markdown	Python	غني بالميزات ونظام إضافات
kramdown	Ruby	يدعم مخرجات متعددة
Pandoc	Haskell	محوّل وثائق عام

محركات العرض

العرض على الطرف العميل

تحليل Markdown آنياً في المتصفح:

// 使用 marked.js
const html = marked.parse('# Hello World');
document.body.innerHTML = html;

المزايا:

• بلا معالجة خادمية
• معاينة فورية
• تخفيف حمل الخادم

العيوب:

• يعتمد على JavaScript
• غير ملائم لـ SEO
• تحميل أولي أبطأ

العرض على الخادم

توليد HTML مسبقاً على الخادم:

// Node.js 示例
const fs = require('fs');
const marked = require('marked');

const markdown = fs.readFileSync('document.md', 'utf8');
const html = marked.parse(markdown);

المزايا:

• ملائم لـ SEO
• سرعة تحميل أعلى
• لا يعتمد على JavaScript على العميل

العيوب:

• كلفة معالجة خادمية
• تعقيد إدارة التخزين المؤقت

توليد مواقع ساكنة

توليد كل الصفحات وقت البناء:

# 使用 VitePress
npm run build

المزايا:

• أسرع تحميل
• أفضل SEO
• أمان مرتفع
• سهل النشر

العيوب:

• دعم محدود للمحتوى الديناميكي
• زمن بناء أطول

آلية التوسعات

نظام الإضافات

تدعم كثير من المُحلّلات إضافات توسعة:

// مثال إضافة markdown-it
const md = require('markdown-it')()
  .use(require('markdown-it-footnote'))
  .use(require('markdown-it-deflist'))
  .use(require('markdown-it-abbr'));

مُعرِض مخصّص

// توليد روابط مخصّصة
const renderer = new marked.Renderer();
renderer.link = function(href, title, text) {
  return `<a href="${href}" target="_blank">${text}</a>`;
};

تحسين الأداء

استراتيجيات التخزين المؤقت

const cache = new Map();

function parseMarkdown(content) {
  const hash = generateHash(content);
  if (cache.has(hash)) {
    return cache.get(hash);
  }
  
  const result = marked.parse(content);
  cache.set(hash, result);
  return result;
}

التحميل الكسول

// تحليل العناصر الظاهرة فقط
const observer = new IntersectionObserver((entries) => {
  entries.forEach(entry => {
    if (entry.isIntersecting) {
      parseAndRender(entry.target);
    }
  });
});

المعالجة المتدفقة

// تحليل متدفق للملفات الكبيرة
const fs = require('fs');
const { Transform } = require('stream');

const markdownTransform = new Transform({
  transform(chunk, encoding, callback) {
    const html = marked.parse(chunk.toString());
    callback(null, html);
  }
});

fs.createReadStream('large-document.md')
  .pipe(markdownTransform)
  .pipe(fs.createWriteStream('output.html'));

مشكلات شائعة

1) مشكلة فواصل الأسطر

قد تختلف معاملة فواصل الأسطر بين المُحلّلات:

سطر 1
سطر 2        ← قد يُفسَّر كفقرة واحدة

سطر 1  
سطر 2        ← مسافتان في نهاية السطر لكسر سطر

سطر 1

سطر 2        ← سطر فارغ يفصل الفقرات

2) مزج HTML

هذا مزيج من **Markdown** و<em>HTML</em>.

انتبه لإغلاق وسوم HTML وتشابكها الصحيح.

3) تهريب المحارف الخاصة

هنا نحتاج إلى تهريب المحرفين \* و\_.

سيناريوهات تطبيق فعلية

1) أنظمة التدوين

مقال Markdown → مولّد موقع ساكن → موقع HTML

2) مواقع الوثائق

.md مستند → VitePress/Docusaurus → وثائق على الويب

3) ملفات README

README.md → GitHub/GitLab → صفحة المشروع الرئيسية

4) تطبيقات الملاحظات

ملاحظات Markdown → عرض لحظي → نص منسّق

الخطوة التالية

الآن وقد فهمت آلية العمل، يمكنك:

• حالات استخدام مفصلة
• اختر المحرر المناسب
• ابدأ بتعلم القواعد الأساسية