يجب أن يعيش توثيقك في Markdown صريح، حتى مع محرر مرئي

اسأل أي منصة توثيق: إذا غادرناها العام المقبل، ماذا سنأخذ معنا؟ الإجابة الجيدة ليست وعداً بالتصدير، بل ملفات يمكن فتحها ومراجعتها وبناؤها خارج المنتج.

المحرر المرئي وMarkdown ليسا خيارين متعارضين. المحرر طريقة تفاعل؛ أما Markdown فهو عقد التخزين والتبادل. الخطر يبدأ عندما تصبح شجرة المحرر الداخلية هي السجل الوحيد، ويصبح Markdown تحويلاً تقريبياً لا يحدث إلا عند المغادرة.

طريقتان لتخزين الكتابة

البعد	Markdown نصي	قاعدة كتل خاصة
المصدر المعتمد	نص على القرص أو في حقل نصي	JSON أو XML خاص بالمنتج
التصدير	نسخ الملفات أو الحقول	محول تختلف دقته حسب نوع الكتلة
المراجعة	فرق أسطر واضح	فرق خاص أو غير مقروء
البحث الخارجي	rg أو أي مفهرس	API المورد
إدخال RAG	مباشر بعد التنظيف	استخراج وتحويل أولاً
كلفة الانتقال	روابط ومكونات وبيانات وصفية وأصول	كل ما سبق إضافة إلى فك الصيغة

لا يعني ذلك أن قاعدة الكتل سيئة. هي مفيدة للتعاون اللحظي والصلاحيات الدقيقة. لكن اختيار التخزين يتحول إلى كلفة انتقال، لذلك يجب قياس مسار الخروج قبل الاعتماد.

ماذا يعني محرر مرئي فوق Markdown؟

تستخدم المحررات الحديثة نموذج مستند داخلياً لتقديم قائمة الأوامر والسحب والتنسيق. السؤال ليس هل توجد هذه الشجرة، بل هل تُحفظ باعتبارها المصدر النهائي.

يحافظ المحرر المعتمد على Markdown على invariant واضح:

1. عند الفتح، يحلل Markdown إلى شجرة مؤقتة.
2. أثناء التحرير، يتعامل المستخدم مع الكتل والاختصارات.
3. عند الحفظ، يحول الشجرة إلى Markdown موثق ثم يتخلص من النموذج المؤقت.

## إعداد webhook

تحقق من التوقيع لكل طلب:

```ts
const valid = verifySignature(payload, header, secret);
```

<Callout title="دوّر الأسرار">
يجب أن تتبع أسرار webhook جدول تدوير مفاتيح API.
</Callout>

أي ميزة لا تستطيع المرور من هذا المسار من دون فقد يجب ألا تُطرح قبل تعريف تمثيل نصي لها.

حدّد مفردات MDX

قد تحتاج الوثائق إلى تنبيهات وتبويبات وبطاقات وأمثلة طلب واستجابة. اسمح بمجموعة مكونات محدودة وموثقة، وحدد لكل مكون:

• السمات المقبولة وأنواعها؛
• تمثيله عند التصدير إلى Markdown محمول؛
• سلوكه إذا لم يعرفه العارض الآخر؛
• ما إذا كان يستطيع تنفيذ شيفرة أو إجراء شبكة؛
• اختبارات الأمان والذهاب والعودة.

لا تسمح باستيرادات JavaScript عشوائية في محتوى يأتي من مستخدمين ثم تعده "Markdown". افصل المحتوى عن كود التطبيق، واعرض العناصر غير المعروفة كنص خامل.

ما الذي تكسبه من عقد Markdown؟

مراجعة مستقلة. تستطيع مقارنة التغييرات بأدوات نصية عادية، حتى لو كان الإنتاج يستخدم قاعدة بيانات.

مسار خروج مفهوم. يظل عليك نقل الأصول والروابط والبيانات الوصفية، لكنك لا تبدأ بفك صيغة كتل مغلقة.

استرجاع أبسط. العناوين والقوائم والجداول والشيفرة تصل إلى الفهرسة من دون تجريف واجهة المتصفح.

اختبار أمني أوضح. يمكنك منع script والاستيرادات والتعبيرات النشطة مع الحفاظ على أمثلة الشيفرة داخل الأسوار.

افصل بين "Markdown هو صيغة التخزين" و"المستودع هو مصدر الحقيقة". قد يحفظ Nibleaf Markdown داخل PostgreSQL ويصدر ZIP، بينما يحفظ Docusaurus الملفات مباشرة في Git. كلاهما يستخدم Markdown، لكن مسار النسخ والاستعادة مختلف.

المقايضات بصراحة

لا يمثل Markdown كل تخطيط بصري من دون اتفاقات إضافية. الجداول الكبيرة صعبة على الهاتف، والتعليقات التعاونية تحتاج معرفات لا تظهر دائماً في الملف، والتزامن الثنائي مع Git يضيف تعارضات. كما أن التصدير النصي وحده لا يحفظ تاريخ قاعدة البيانات أو الصلاحيات أو الأصول.

لهذا يجب أن يشمل اختبار الملكية المحتوى والأصول والبيانات الوصفية والروابط وحالة النشر. "لدينا زر تصدير" ليس نتيجة استعادة.

أين تقع المنصات الشائعة؟

Docusaurus وStarlight وMkDocs يبدأون من ملفات، ولذلك يكون المستودع عادة السلطة. GitBook وMintlify يقدمان مسارات Git قوية تناسب الفرق الهندسية، لكن عليك التحقق من الاتجاه الفعلي للمزامنة والمكونات الخاصة. BookStack وWiki.js وNibleaf منصات قاعدة بيانات بدرجات مختلفة من دعم Markdown والتصدير.

لا تعتمد على اسم الفئة. افتح تصديراً حقيقياً، واقرأ خمسة ملفات صعبة، وابنها بأداة أخرى.

كيف يطبق Nibleaf العقد؟

يحفظ Nibleaf محتوى الصفحة كـMarkdown، ويحوّل المحرر النص إلى نموذج TipTap مؤقتاً ثم يعيده عند الحفظ. ينشئ النشر لقطة غير قابلة للتغيير، ويمكن تصدير المشروع إلى ملفات Markdown. تدعم مفردات MDX المعروفة مكونات موثقة، بينما يجب أن تبقى العناصر النشطة غير الموثوقة خاملة في المخرجات العامة.

هذه ادعاءات مصدر يجب ربطها بمراجعة محددة. لا تثبت تلقائياً أن صورة عامة أقدم تحتوي السلوك نفسه، ولا أن كل مكون خارجي يدور من دون فقد.

اختبار الذهاب والعودة قبل الالتزام

أنشئ عينة تشمل:

• عناوين متداخلة وقوائم مهام وجدولاً؛
• كتلة شيفرة تحتوي أقواساً ووسوم MDX كنص؛
• تنبيهاً وبطاقة ورابطاً داخلياً وصورة؛
• نصاً عربياً مع أمر LTR ومعرف مثل user_id؛
• بيانات وصفية ومساراً وترجمة بمسار مختلف.

مررها عبر الاستيراد والتحرير والحفظ والتصدير ثم قارن المعنى والروابط والسمات. ابنِ التصدير بأداة ثانية، وافتحه من دون حساب المورد. أعد التجربة بعد ترقية كبيرة للمحرر.

أخرج مع النتيجة سجل فقد دلالي. لكل كتلة أو مكوّن MDX غير مدعوم، سجّل موضعه ومعناه المقصود وتمثيله البديل وخطورته ومالك المعالجة. طبّق ذلك على الملفات المضمّنة والمخططات المولدة والثنائيات الكبيرة في Git LFS؛ مؤشر LFS من دون الكائن ليس أصلاً قابلاً للنقل. اختبر الروابط النسبية وجلب كائنات LFS من حساب وبيئة نظيفين.

اجعل التحذير مانعًا للنشر إذا أسقط مثالًا قابلاً للتنفيذ أو تنبيه أمان أو هدف رابط أو سمة مكوّن أو لغة أو أصلاً لازمًا لفهم الصفحة. يمكن قبول تطبيع تنسيق لا يغير المعنى بعد المراجعة. عدد ملفات صحيح مع صندوق فارغ بدل كتلة غير مدعومة هو فشل، لا تدهور مقبول.

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