الميزات
تشرح هذه الصفحة كل ميزة مدمجة وفق تنفيذها الفعلي في الشيفرة المصدرية.
العرض التزايدي
تستخدم المعاينة عرضًا تزايديًا على مستوى الكتل للحفاظ على سرعة الاستجابة مع المستندات الكبيرة:
- تقسيم الكتل (
splitIntoBlocks): يُقسَّم المصدر عند أسطر عناوين ATX (من#إلى######). لا يُستخدم المحتوى داخل سياج شيفرة محدد بعلامات الاقتباس الخلفية أو التلدة كنقطة تقسيم، وتُحفظ أيضًا العناوين داخل الحاويات المخصصة:::. يُعالَج المستند الذي لا يحتوي على عناوين ككتلة واحدة. - عرض كل كتلة على حدة: لا تُعاد معالجة الكتل عبر markdown-it / KaTeX إلا إذا تغيّرت بصمة محتواها. تعيد الكتل غير المتغيرة استخدام عقد DOM الحالية مباشرةً، بما فيها رسومات SVG للخرائط الذهنية التي فُعّلت تفاعليًا.
- تخزين مؤقت حسب بصمة المحتوى: تُخزَّن نتائج العرض حسب بصمة المحتوى (بصمة سريعة على نمط djb2 مع الطول)، لذا تستفيد عمليات التراجع والإعادة ونسخ الفقرات المتطابقة من التخزين المؤقت أيضًا. عندما يتجاوز عدد الإدخالات 800، تُحذف البصمات التي لم تعد موجودة في المستند. تُحتفَظ بإدخالات الكتل الحالية، لذلك قد يتجاوز المستند الذي يضم أكثر من 800 كتلة مختلفة هذا الحد.
- إعادة الترتيب: تُنقَل الكتل التي تغيّر ترتيبها بإضافة العقد الحالية إلى
DocumentFragment. - تأخير تكيفي (
adaptiveDebounceMs(docLength, base = 120, max = 600)): تساوي فترة الانتظار قبل العرضbase + floor(docLength / 20000) * 60، بحد أقصىmax. غيّرها عبرrenderDebounce، أو اضبطrenderDebounce: falseللعرض المتزامن. content-visibility: auto: تُغلَّف كل كتلة بعنصر.md-editor-blockلتجاوز حساب التخطيط والرسم للكتل خارج الشاشة.
فشل عرض كتلة واحدة لا يُفرغ المعاينة بأكملها؛ يُعرض مصدر تلك الكتلة بعد تهريب المحارف داخل <pre> بدلًا منها.
صيغ KaTeX الرياضية
تعرض إضافة الرياضيات المستقلة لـ markdown-it الصيغ باستخدام KaTeX (من دون الاعتماد على markdown-it-texmath):
- الصيغ المضمّنة:
$E=mc^2$— يجب ألا يكون ا لمحتوى فارغًا أو يحتوي على$أو سطر جديد. تُستبعد استدلاليًا النصوص الشبيهة بالمبالغ المالية مثل$5أو$10.50. - الصيغ المنفصلة:
تُدعَم صيغة السطر الواحد ($$\int_0^1 x^2 \, dx$$
$$ ... $$) والصيغة متعددة الأسطر. ملفات CSS الخاصة بـ KaTeX مضمّنة في الحزمة. للتعطيل، استخدمmath: false.
خرائط Markmap الذهنية
اكتب كتلة مسيّجة من النوع ```mindmap يكون محتواها مخططًا هرميًا بصيغة Markdown:
```mindmap
# Root topic
## Branch one
- Child A
- Child B
## Branch two
- Child C
```
تتتبّع قاعدة الكتلة عمق تداخل الأسوار، فتحافظ على أسوار الشيفرة داخل الخريطة الذهنية. ينتج العرض المتزامن عنصرًا نائبًا <div>؛ تستورد Renderer.hydrate(container) المكتبتين markmap-lib وmarkmap-view بصورة غير متزامنة، ثم تحوّل كل عنصر نائب إلى SVG تفاعلي. أخطاء التفعيل التفاعلي ليست قاتلة. للتعطيل، استخدم mindmap: false.
تمييز الشيفرة مع زر نسخ
تُميَّز كتل الشيفرة المسيّجة باستخدام highlight.js. تسجّل عملية البناء مجموعة ثابتة من اللغات: JavaScript وTypeScript وPython وJSON وBash/Shell وCSS وXML/HTML/SVG وSQL وYAML وMarkdown وGo وRust وJava وC وC++ (مع الأسماء البديلة الشائعة مثل js وts وpy وsh وyml وmd وrs وc++). تُكتشف اللغات غير المعروفة تلقائيًا؛ وإذا فشل الاكتشاف، يُعرض نص عادي مع تهريب المحارف.
تُغلَّف كل كتلة مميّزة بحاوية على نمط macOS تضم نقاطًا ملونة واسم اللغة وزر نسخ. يستخدم الزر تفويض الأحداث في لوحة المعاينة، ويلجأ إلى document.execCommand('copy') عند غياب Clipboard API. للتعطيل، استخدم codeHighlight: false.
إجراءات شريط الأدوات
في وضع complex، يتكوّن شريط الأدوات من الإجراءات الـ 22 التالية بهذا الترتيب الافتراضي:
| # | اسم الإجراء | الوظيفة |
|---|---|---|
| 1 | heading | عنوان |
| 2 | bold | عريض (Ctrl+B) |
| 3 | italic | مائل (Ctrl+I) |
| 4 | link | رابط (Ctrl+K) |
| 5 | image | إدراج صورة |
| 6 | video | إدراج فيديو |
| 7 | youtube | إدراج فيديو YouTube |
| 8 | quote | اقتباس |
| 9 | ul | قائمة غير مرتبة |
| 10 | ol | قائمة مرتبة |
| 11 | tasklist | قائمة مهام |
| 12 | mention | إشارة (@) |
| 13 | doclink | إدراج رابط مستند |
| 14 | code | كتلة شيفرة |
| 15 | table | جدول |
| 16 | math | صيغة رياضية |
| 17 | mindmap | إدراج خريطة ذهنية |
| 18 | hr | خط أفقي |
| 19 | tips | إدراج مربع تنبيه |
| 20 | preview | تبديل المعاينة |
| 21 | help | اختصارات لوحة المفاتيح |
| 22 | theme | تبديل السمة |
التسميات المدمجة باللغة الإنجليزية. خصّص label لكل عنصر لترجمة التلميحات والأسماء الميسّرة. تفتح بعض الإجراءات نوافذ منبثقة أو محددات قوالب: الصور والفيديو وYouTube والجداول والصيغ (قوالب) والخرائط الذهنية (قوالب) والتنبيهات (شبكة أنواع) والمساعدة. اضبط شريط الأدوات باستخدام الخيار toolbar كما هو موضح في الإعدادات.
اختصارات لوحة المفاتيح
تُعرَّف الاختصارات المدمجة في DEFAULT_SHORTCUTS. يقابل Mod مفتاح Ctrl على Windows/Linux ومفتاح Cmd على macOS.
| المفتاح | الإجراء | الوصف |
|---|---|---|
Mod-b | bold | عريض |
Mod-i | italic | مائل |
Mod-Alt-1 | heading | عنوان |
Mod-k | link | إدراج رابط |
Mod-Alt-c | code | كتلة شيفرة |
Mod-Shift-. | quote | اقتباس منفصل |
Mod-Shift-8 | ul | قائمة غير مرتبة |
Mod-Shift-7 | ol | قائمة مرتبة |
Mod-Shift-9 | tasklist | قائمة مهام |
Mod-Alt-m | math | صيغة رياضية |
Mod-Alt-p | preview | تبديل المعاينة |
Mod-Shift-l | theme | تبديل السمة |
يفتح زر المساعدة في شريط الأدوات نافذة تعرض هذه الاختصارات بأشكال مفاتيح مرئية، مع مرجع سريع لقوائم المهام والإشارات وروابط المستندات والصيغ والخرائط الذهنية والتنبيهات.
رفع الصور
وفّر onImageUpload: (file: File) => Promise<string>. تُستدعى الدالة عند لصق ملف صورة أو إفلاته في المحرر. تقبل نافذة الصورة عنوان URL ولا تتيح اختيار ملف. أعد عنوان URL عامًا للصورة؛ يُدرج المحرر  عند المؤشر (ويستخدم اسم الملف دون الامتداد نصًا بديلًا). تُتجاهَل أخطاء الرفع بصمت، ويمكن للمستخدم إعادة المحاولة.
@mention
مرّر الخيار mention لتفعيل قائمة قابلة للبحث عند كتابة المستخدم @:
- تعيد
onMentionSearch(query)عناصرMentionItemالمطابقة. - تعيد
onMentionSelect(item)النص المراد إدراجه. القيمة الافتراضية هي[@label](mention:id)، ويحوّلها العارض إلى شارة منسّقة. - يضبط
minChars(افتراضيًا0) وmaxItems(افتراضيًا8) القائمة.
تدعم القائمة التنقل باستخدام ArrowUp/ArrowDown وEnter/Tab وEscape، وتُغلَق عندما يفقد المحرر التركيز. في المعاينة، لا يتحول نص @ العادي مثل @media إلى شارة؛ وحدها الروابط التي تستخدم المخطط mention: تصبح شارات. أما في المحرر، فيظل بإمكان هذا النص تشغيل دالة البحث المضبوطة.
روابط المستندات
مرّر الخيار docLink لتفعيل قائمة البحث عن المستندات بعد حرف التشغيل (افتراضيًا /):
- تعيد
onDocSearch(query)عناصرDocItemالمطابقة. - تجلب
onFetchDocMeta(url)العنوان والصورة المصغّرة والوصف. يستخدم التنفيذ المدمجfetch+DOMParserلقراءة وسوم Open Graph، وقد يفشل إذا لم يسمح الخادم ذو المصدر المختلف بسياسة CORS. استخدم وكيلًا خلفيًا مخصصًا عند الحاجة. - يتحكم
insertStyleفي أسلوب الإدراج:'auto'(بطاقة عند توفر البيانات الوصفية)، أو'card'، أو'link'.
يُدرَج المستند المحدد كرابط عادي أو بطاقة :::doc-link تعرض العنوان والصورة المصغّرة والوصف واسم المضيف في معاينة قابلة للنقر.
كتل التنبيهات والملاحظات
اكتب حاوية ::: بأحد الأنواع الستة. يمكن إضافة عنوان اختياري بعد النوع في سطر الافتتاح:
:::notice
This is a notice.
:::
:::warning[Title here]
Warning content.
:::
الأنواع المدعومة: notice وinfo وtip وsuccess وwarning وdanger. يُعرض كل نوع مع أيقونة وحد أيسر ملون وعنوان. يفتح زر التنبيهات في شريط الأدوات محددًا مرئيًا للأنواع الستة. للتعطيل، استخدم tips: false.
قوائم المهام
تُعرض عناصر القائمة المطابقة لـ - [ ] أو - [x] (مع مسافات بيضاء اختيارية داخل القوسين) كمربعات اختيار معطّلة. انتبه إلى اصطلاح المشروع: تظهر - [ ] محددة (بالأخضر)، وتظهر - [x] غير محددة — بعكس GitHub Flavored Markdown. يبدّل زر قائمة المهام العلامات في السطر الحالي أو الأسطر المحددة.