ترحيل التوثيق إلى Nibleaf

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

اختيار المصدر

لاستيراد Mintlify، أدخل owner/repository وفرعًا اختياريًا. يفضّل Nibleaf الملف docs.json، ويحل مراجع $ref المحلية إلى ملفات .json داخل المستودع، ويقرأ اللغات والإصدارات والمنتجات وعلامات التبويب وعناصر القوائم والمجموعات وصفحات الجذر نسبةً إلى ذلك الملف، ويستورد الصفحات الداخلية المرتبطة التي أُغفلت من التنقل، ويحافظ على إعدادات الهدف الحالية عندما تكون معبأة بالفعل. تتحول لغات Mintlify إلى لغات Nibleaf، وتتحول إصدارات Mintlify إلى إصدارات توثيق في Nibleaf مدعومة بفروع. تنشئ عملية الاستيراد الواحدة 500 عقدة تنقل كحد أقصى، بما فيها المجموعات والصفحات؛ ويجب تقسيم المصادر التي تتجاوز هذا الحد ومطابقة إجمالياتها قبل التحويل.

لا يقرأ Nibleaf رابط محرّر خاصًا في Mintlify Cloud. إذا لم تكن مساحة العمل مرتبطة بمستودع GitHub عام، فصدّر مصدرها أو انشره أولًا إلى مستودع عام مؤقت، وأزل الأسرار والمحتوى الخاص، ثم استخدم ذلك المستودع للتدرّب على الترحيل.

بالنسبة إلى Ghost، افتح الإعدادات ← Labs ← Import/Export في Ghost Admin وصدّر محتوى الموقع وإعداداته بصيغة JSON. ارفع الملف وأدخل أصل الموقع، مثل https://docs.example.com، كي يتمكن Nibleaf من حل مسارات صور __GHOST_URL__ ومسارات /content/images/... العادية قبل نسخ الصور المتاحة إلى تخزين المشروع. يستورد Nibleaf المنشورات والصفحات العامة المنشورة فقط، ويتخطى المسودات والمنشورات المجدولة والمحتوى المقيد بالأعضاء أو الاشتراك المدفوع أو فئات الوصول، حتى لا يتحول المحتوى المحمي إلى توثيق عام. صدّر routes.yaml وعمليات إعادة التوجيه بصورة منفصلة، ثم أعد إنشاءها من الإعدادات ← عمليات إعادة التوجيه بعد التحقق من كل وجهة. لا يشمل مستورد المحتوى حسابات الأعضاء أو النشرات أو إعدادات البريد أو كود القالب.

إنشاء خط أساس

قبل الاستيراد، سجّل:

• مراجعة المصدر أو الطابع الزمني للتصدير؛
• عدد الصفحات والأصول؛
• التسلسل الهرمي للتنقل وعمليات إعادة التوجيه؛
• عدد المحتوى المنشور والمسودات كلًا على حدة؛
• النطاقات المخصصة، وقواعد الرابط الأساسي (canonical)، والفهرسة، وعلاقات اللغات؛
• عينات تمثيلية من Markdown ومكونات MDX والجداول والرسومات التخطيطية والتنزيلات؛
• استعلامات البحث التي يجب أن تعيد صفحة معينة.

صدّر المصدر أو أنشئ نسخة احتياطية منه، وحدد المسؤول عن التحويل والتراجع.

الاستيراد وفحص التحذيرات

شغّل الاستيراد في مشروع جديد أو فرع معزول. اقرأ الملخص وعالج كل صفحة أو أصل تم تخطيه، وكل اسم مسار مكرر، وكل إعداد غير مدعوم. قد يحتفظ Nibleaf برابط المصدر عندما يتعذر نسخ أحد الأصول؛ ولا يُعد ذلك ترحيلًا دائمًا إذا كان المصدر سيُزال.

ابحث في المصدر المستورد عن أسماء المضيف القديمة، وبادئات /docs، ووسوم المكونات الخاصة بالمصدر، وبيانات الاعتماد المضمّنة، وروابط الأصول المطلقة.

التحقق من التكافؤ

اتبع هذا الترتيب:

1. قارن عدد الصفحات وتسلسلها الهرمي.
2. عاين صفحة واحدة لكل نمط محتوى.
3. قارن تقسيم اللغات والإصدارات وتنقل المنتجات والقوائم والفصل بين منشورات Ghost وصفحاته.
4. افحص بالزحف الروابط الداخلية والصور والتنزيلات وعمليات إعادة التوجيه والمسارات المفقودة.
5. اختبر استعلامات البحث المسجلة في خط الأساس بكل لغة.
6. افتح الإعدادات ← اللغات وعالج كل صفحة مفقودة مقارنةً باللغة الافتراضية.
7. افحص العنوان والوصف والرابط الأساسي وhreflang وrobots وخريطة الموقع والبيانات المنظّمة في استجابة HTML الأولية.
8. تحقق من سلوك لوحة المفاتيح والهاتف المحمول في صفحات تمثيلية.
9. انشر إلى اسم مضيف غير أساسي وكرر الفحوص في أثناء تسجيل الخروج.
10. تدرّب على التراجع: أعد اسم مضيف المصدر وتأكد من بقاء المصدر قابلًا للتحرير قبل جدولة تغيير DNS.

لا تحذف المصدر أو تغيّر DNS قبل أن تتوفر للبديل نسخة تراجع مختبَرة.

التصدير والتعافي

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

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