كيف أُحضِر ملفات Markdown الموجودة لديّ إلى VeloCMS؟

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

الإجابة الصريحة: لا يوجد بعد مستورد Markdown بالجملة

تملك صفحة الاستيراد في VeloCMS (لوحة التحكم ← استيراد المحتوى) مستوردات مخصصة لعدة منصات، لكن لا توجد منطقة إسقاط تقرأ مجلداً أو ملف ZIP من ملفات .md خام، ولا محلّل لبيانات الرأس (front matter)، ولا جدول معاينة يوضح أي المنشورات جاهزة للنشر. إن كنت تتوقع ذلك، فهو غير موجود اليوم. اختصار واحد قبل أن تلجأ إلى سكريبت: إذا كان موقعك الثابت القديم لا يزال متاحاً على الإنترنت، يمكن لمستورد «أي موقع» في الصفحة ذاتها أن يزحف إليه — إذ يكتشف المنشورات عبر خريطة الموقع (sitemap) وخلاصة RSS ويستورد محتواها مباشرة، دون أي تعامل مع Markdown. أما بالنسبة للملفات غير المتصلة بالإنترنت، فما هو متاح فعلاً طريقتان لنقل المحتوى بنفسك.

لعدد قليل من المنشورات: أعد بناءها في المحرر

انتقل إلى لوحة التحكم ← المقالات ← مقال جديد، واكتب أو نسّق محتوى كل منشور مباشرة في محرر VeloCMS، ثم اضبط العنوان وslug والوسوم والمقتطف بنفسك اعتماداً على بيانات الرأس التي كانت لديك. هذه طريقة يدوية لا تلقائية — لكنها واقعية وموثوقة لمدونة تضم أقل من 20 منشوراً تقريباً.

لأرشيف أكبر: اكتب سكريبتاً يستخدم واجهة API

بالنسبة لعشرات أو مئات الملفات، إعادة بناء كل منشور يدوياً ليست واقعية. يملك VeloCMS واجهة REST API عامة لإنشاء المنشورات — POST /api/v1/posts — تقبل title وslug وcontent_html وexcerpt وstatus (مسودة أو منشور) وtags وcategory_slug. أنشئ مفتاحاً بنطاق posts:write من لوحة التحكم ← الإعدادات ← متقدم ← مفاتيح API (يتطلب هذا خطة Pro أو أعلى). من هناك، اكتب سكريبتاً قصيراً: اقرأ بيانات الرأس YAML الخاصة بكل ملف باستخدام محلّل YAML قياسي، وحوّل متن Markdown إلى HTML باستخدام محوّل تثق به، وقرّر بنفسك كيف تُطابق حقول بيانات الرأس مع حقول VeloCMS. هذا أكثر موثوقية من أي أداة مطابقة تلقائية عامة — فمولّدات المواقع الثابتة المختلفة تستخدم فعلاً أسماء حقول مختلفة (مثلاً date في Jekyll مقابل publishDate في Hugo مقابل date في Gatsby)، وأنت وحدك من يعرف أيّها ينطبق على ملفاتك.

import fs from "node:fs";
import matter from "gray-matter";
import { marked } from "marked";

const files = fs.readdirSync("./posts").filter((f) => f.endsWith(".md"));

for (const file of files) {
  const { data, content } = matter(fs.readFileSync(`./posts/${file}`, "utf8"));

  await fetch("https://yourname.velocms.org/api/v1/posts", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.VELOCMS_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      title: data.title,
      slug: data.slug, // omit to let VeloCMS generate one from the title
      content_html: marked.parse(content),
      excerpt: data.description ?? data.summary,
      tags: data.tags ?? [],
      status: "draft",
    }),
  });
}

الصور

لا يوجد اصطلاح لمجلد images/ أو assets/ يقرأه المستورد تلقائياً، لأنه لا يوجد مستورد أصلاً. ارفع كل صورة من لوحة التحكم ← الوسائط (أو عبر POST /api/v1/media بمفتاح media:write) واستخدم الرابط الذي يُعاد داخل content_html الخاص بمنشورك. إذا كانت صورك مستضافة في مكان آخر بالفعل — GitHub أو CDN أو رابط مطلق — يمكنك الإشارة مباشرة إلى ذلك الرابط بدلاً من ذلك؛ لا يتطلب VeloCMS منك إعادة استضافتها.

بعد الدخول

راجع كل منشور مستورد في لوحة التحكم ← المقالات قبل أن يُنشر: تحقق من أن التنسيق ظهر بشكل صحيح، وأن الصور تحمّلت، وأن عناوين slug تبدو سليمة. حين تصبح مجموعة منشورات جاهزة، حدّدها واستخدم إجراء النشر الجماعي في جدول المنشورات بدلاً من فتح كل منشور على حدة.

أسئلة شائعة

• هل يمكنني استيراد ملفات .mdx (MDX مع JSX)؟ ليس مباشرة — مكوّنات JSX في MDX لن تُعرض عبر أي من الطريقتين أعلاه. حوّلها أولاً إلى Markdown أو HTML عادي وأعد إنشاء أي مكونات تفاعلية ككتل في محرر VeloCMS أو منشئ الصفحات.
• ما HTML الذي تقبله الواجهة API فعلياً؟ أياً كان ما يُخرجه محوّل Markdown لديك. الوسوم القياسية — العناوين والفقرات والقوائم والروابط والصور وكتل الكود المسيّجة — تُعرض بشكل صحيح عبر content_html؛ أي شيء غير معتاد يستحق التحقق منه في مسودة قبل النشر.
• هل يمكنني تعديل منشور بعد إنشائه عبر الواجهة API؟ نعم — PATCH /api/v1/posts/{id} بنفس مفتاح posts:write يحدّث منشوراً أنشأته بالفعل، أو يمكنك ببساطة فتحه من لوحة التحكم ← المقالات وتعديله مباشرة.
• هل يمكنني الاستيراد من Obsidian بهذه الطريقة؟ نعم — صيغة Markdown في Obsidian قياسية، لذا يعمل نفس مسار 'التحويل إلى HTML ثم الإرسال'. روابط [[اسم الصفحة]] الداخلية في Obsidian لا تنتقل تلقائياً وتحتاج إلى أن تصبح روابط عادية.