كيف أستورد ملفات Markdown الموجودة دفعةً واحدة إلى VeloCMS؟

كثير من الكتّاب والمطورين لديهم مجلد من ملفات .md — ربما من موقع Jekyll أو Hugo أو Eleventy، أو من Obsidian، أو من سنوات طويلة من الملاحظات الشخصية التي قرروا أخيراً نشرها. يستطيع VeloCMS استيرادها دفعةً واحدة. إليك العملية الدقيقة.

ما الذي يتوقعه VeloCMS من ملفات Markdown

لضمان استيراد نظيف، يجب أن يحتوي كل ملف .md على كتلة YAML في الرأس. الحد الأدنى المطلوب هو العنوان فحسب. كلما أضفت المزيد من الحقول، زادت قدرة VeloCMS على أتمتة عملية الاستيراد. إليك المجموعة الكاملة من الحقول المدعومة:

---
title: "Your Post Title"
slug: your-post-slug          # Optional — auto-generated from title if absent
excerpt: "Short summary"       # Optional — first paragraph used if absent
date: 2025-11-01               # Optional — import date used if absent
tags:
  - javascript
  - tutorial
author: "Your Name"            # Optional — falls back to blog author
status: published              # Optional — 'draft' or 'published' (default: draft)
coverImage: ./images/cover.jpg # Optional — relative to the .md file
---

اصطلاح تسمية الملفات

يقبل مستورد VeloCMS أي اسم للملف — إذ يُؤخذ الـ slug من بيانات الرأس لا من اسم الملف. لكن إذا لم تتضمن بيانات الرأس slug، يولّد VeloCMS واحداً من اسم الملف بحذف امتداد .md وتحويله إلى kebab-case. إذن ملف اسمه BuildingRestAPI.md سيصبح الـ slug الخاص به building-rest-api. الملفات التي تحتوي تواريخ في اسمها (2025-11-01-building-rest-api.md، وهو اصطلاح Jekyll) تُحذف منها بادئة التاريخ تلقائياً.

بنية مجلد الصور

لاستيراد الصور بشكل صحيح، ضعها في مجلد باسم images/ أو assets/ على نفس مستوى ملفات .md. يرفع مستورد ZIP في VeloCMS الصور المُشار إليها إلى حاوية تخزين R2 الخاصة بك ويعيد كتابة مسارات الصور في المقالات المستورة. أما الصور التي تحمل روابط مطلقة (https://...) فتُستورد دون أي تعديل — يترك VeloCMS روابط الصور الخارجية كما هي.

# Recommended ZIP structure for batch import:
your-posts.zip
├── post-one.md
├── post-two.md
├── post-three.md
└── images/
    ├── hero-post-one.jpg
    ├── diagram-post-two.png
    └── screenshot-post-three.webp

تشغيل الاستيراد الجماعي

في لوحة تحكم VeloCMS، انتقل إلى Admin → Tools → Import → Markdown Batch. انقر على 'Choose ZIP file' واختر أرشيفك. يعرض VeloCMS جدول معاينة يتضمن عنوان كل منشور والـ slug والتاريخ المكتشف والحالة (جاهز / تحذير / خطأ). تظهر التحذيرات حين تفتقر بيانات الرأس إلى حقول مطلوبة أو تكون مراجع الصور معطوبة. راجع الجدول وحلّ أي تحذيرات، ثم انقر على 'Import All'. تُستورد المقالات كمسودات ما لم تحدد status: published في بيانات الرأس.

التعامل مع اختلافات بيانات الرأس

تستخدم أنظمة الموقع الثابت المختلفة أسماء حقول مختلفة قليلاً في بيانات الرأس. يتعامل مستورد VeloCMS مع أكثر الاختلافات شيوعاً تلقائياً: يستخدم Jekyll الحقل date، ويستخدم Hugo الحقل publishDate أو date، بينما يستخدم Gatsby/MDX عادةً date وdescription. يعيّن المستورد هذه الأسماء البديلة: date → published_at، وdescription أو summary → excerpt، وtags أو categories → tags. الحقول التي لا تتطابق مع أي حقل معروف في VeloCMS تُحفظ في JSON الخاص بالبيانات الوصفية المخصصة للمنشور.

بعد الاستيراد: المراجعة والنشر

بعد الاستيراد الجماعي، تصل جميع المنشورات إلى Admin → Posts كمسودات (أو منشورة إن نصّت بيانات الرأس على ذلك). رتِّب حسب تاريخ الاستيراد لرؤية الدفعة الجديدة. تصفّح عيّنة من المنشورات للتحقق من صحة التنسيق وتحميل الصور وصحة عناوين slug. للمنشورات التي تريد نشرها فوراً، حددها واستخدم إجراء النشر الجماعي في جدول المنشورات.

أسئلة شائعة

• هل يمكنني استيراد ملفات .mdx (MDX مع JSX)؟ لا — مكونات JSX في MDX لا تعمل في VeloCMS. استورد نسخة .md وأعد إنشاء أي مكونات تفاعلية مدعومة بـ JSX ككتل في محرر VeloCMS.
• ما امتدادات Markdown المدعومة؟ CommonMark القياسي إضافةً إلى GFM (GitHub Flavoured Markdown) — الجداول والنص المشطوب وقوائم المهام وكتل الكود المسيّجة جميعها مدعومة.
• هل يمكنني الاستيراد من Obsidian؟ نعم — صيغة Markdown في Obsidian هي CommonMark القياسي. الروابط الداخلية في Obsidian ([[اسم الصفحة]]) لا تنتقل، لكن الروابط العادية والصور والـ callouts تنتقل بشكل سليم.
• هل تُسبب عناوين slug المكررة مشكلة؟ إذا كان منشور بنفس الـ slug موجوداً بالفعل، يتخطاه المستورد ويشير إليه كتعارض في تقرير الاستيراد.
• هل يمكنني إعادة الاستيراد بعد تعديل الملفات محلياً؟ نعم — إعادة استيراد ZIP يحتوي ملفات بنفس عناوين slug لمنشورات موجودة سيظهرها كتعارضات. يمكنك اختيار 'overwrite' أو 'skip' لكل منشور.