إنشاء “Code Vault” خاص بك لجلب الأكواد من GitHub وعرضها في مدونتك.

مقدمة

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

بدلاً من نسخ كل كود يدوياً داخل المقالات، يمكنك أتمتة دورة كاملة تبدأ من قراءة الملفات عبر ما هو الـ API؟ شرح المفهوم بعيداً عن التعقيد التقني، ثم تمر عبر طبقة معالجة تنظّف المحتوى وتضيف البيانات الوصفية، وتنتهي بواجهة عرض داخل ووردبريس. هذه البنية ترفع الكفاءة التحريرية، وتقلل التكرار، وتمنحك تحكماً أفضل في جودة المحتوى بما ينسجم مع متطلبات EEAT.

ما هو “Code Vault” عملياً؟

Code Vault ليس مجرد صفحة تعرض ملفات برمجية، بل طبقة وسيطة بين مستودعك وواجهة النشر. هذه الطبقة تجمع الملفات من فرع محدد، تستخرج اسم الملف، اللغة، آخر تحديث، رابط المصدر، ووصفاً موجزاً، ثم تخزن الناتج بصيغة مناسبة للعرض أو التخزين المؤقت.

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

الفائدة التقنية والتحريرية

• تقليل النسخ اليدوي بين المستودع والمدونة.
• توحيد طريقة عرض المقاطع البرمجية.
• ربط كل كود بشرح وسيناريو استخدام حقيقي.
• تحسين الأرشفة الداخلية والبحث داخل الموقع.
• إمكانية التحديث التلقائي عبر Webhook أو جدولة دورية.

المعمارية المقترحة لتدفق البيانات

أنصح ببناء المعمارية على ثلاث طبقات: طبقة جلب، طبقة معالجة، وطبقة عرض. الجلب يتم عبر REST API الخاصة بـ GitHub، بينما تقوم طبقة المعالجة بتنظيف البيانات وبناء نموذج موحد، ثم تُرسل النتيجة إلى ووردبريس عبر Custom Post Type أو صفحة مخصصة.

إذا كنت تريد فهماً أعمق لاختيار نوع التكامل المناسب، فراجع الفرق بين REST و SOAP و GraphQL: متى نختار كل نوع؟. وفي حالة GitHub، غالباً يكون REST API كافياً لبناء هذا السيناريو بسرعة ووضوح.

نقطة الاتصال الأساسية:
GET /repos/{owner}/{repo}/contents/{path}
تُستخدم لاستعراض الملفات داخل مجلد معين. ويمكن تمرير الفرع عبر ref للوصول إلى نسخة محددة من الكود.

خطوات بناء سكربت الجلب والمعالجة

قبل كتابة أي سطر برمجي، حدّد ما تريد عرضه فعلياً. هل ستجلب كل الملفات أم فقط الملفات التعليمية؟ هل تريد تجاهل ملفات التهيئة مثل package-lock.json؟ وهل ستعرض المحتوى كاملاً أم مقتطفات مختارة؟ هذه الأسئلة تحدد منطق الفلترة لاحقاً.

1. أنشئ رمز وصول شخصي محدود الصلاحيات من GitHub.
2. خزّن الرمز في ملف .env كما شرحنا في أمن البيانات: كيفية تخزين المفاتيح السرية في ملفات .env..
3. أرسل طلب GET لجلب قائمة الملفات.
4. فلتر النتائج حسب الامتداد أو اسم المجلد.
5. اجلب محتوى كل ملف مطلوب من رابط download_url.
6. كوّن كائناً موحداً يحتوي العنوان والوصف واللغة والمحتوى والرابط الأصلي.
7. احفظ النتيجة محلياً أو ادفعها إلى ووردبريس عبر REST API.

import fetch from "node-fetch";
import dotenv from "dotenv";

dotenv.config();

const owner = "your-username";
const repo = "your-repo";
const path = "snippets";
const branch = "main";

const headers = {
  "Authorization": `Bearer ${process.env.GITHUB_TOKEN}`,
  "Accept": "application/vnd.github+json"
};

async function fetchRepoContents() {
  const endpoint = `https://api.github.com/repos/${owner}/${repo}/contents/${path}?ref=${branch}`;
  const response = await fetch(endpoint, { headers });

  if (!response.ok) {
    throw new Error(`GitHub API error: ${response.status}`);
  }

  const items = await response.json();

  const codeFiles = items.filter(item =>
    item.type === "file" &&
    [".js", ".ts", ".py", ".json"].some(ext => item.name.endsWith(ext))
  );

  const enrichedFiles = await Promise.all(
    codeFiles.map(async (file) => {
      const rawResponse = await fetch(file.download_url);
      const content = await rawResponse.text();

      return {
        title: file.name,
        slug: file.name.toLowerCase().replace(/\./g, "-"),
        source_url: file.html_url,
        download_url: file.download_url,
        language: file.name.split(".").pop(),
        content
      };
    })
  );

  return enrichedFiles;
}

fetchRepoContents()
  .then(data => console.log(JSON.stringify(data, null, 2)))
  .catch(error => console.error(error.message));

إرسال الأكواد إلى ووردبريس

أفضل أسلوب عملي هو إنشاء نوع محتوى مخصص لكل عنصر داخل Code Vault. بهذه الطريقة يصبح لكل كود صفحة مستقلة قابلة للأرشفة، ويمكنك إضافة شرح بشري، حالات استخدام، وروابط إلى شروحات مرتبطة بدلاً من عرض الملف وحده.

ولفهم مكونات الطلب بشكل أدق، يفيدك الرجوع إلى تشريح طلب الـ API: الـ Endpoint، الـ Headers، والـ Body مع لغة الـ JSON: كيف تقرأ وتكتب البيانات التي تفهمها الآلات.

async function sendToWordPress(snippet) {
  const endpoint = "https://your-site.com/wp-json/wp/v2/code_vault";
  const response = await fetch(endpoint, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${process.env.WP_TOKEN}`
    },
    body: JSON.stringify({
      title: snippet.title,
      status: "publish",
      content: `
تمت مزامنة هذا الملف تلقائياً من GitHub.
${snippet.content.replace(/
عرض الملف الأصلي
`

    })

  });
  if (!response.ok) {

    throw new Error(`WordPress API error: ${response.status}`);

  }
  return response.json();

}

ملاحظة أمنية:

لا تضع أي Token داخل القالب الأمامي للموقع. يجب تنفيذ الجلب والإرسال على الخادم أو عبر بيئة أتمتة آمنة مثل استخدام Pipedream للمبرمجين: دمج Node.js مع الأتمتة.

التحديث التلقائي: هل تختار الجدولة أم Webhooks؟
إذا كانت مستودعاتك تتغير على فترات ثابتة، فجدولة المهمة باستخدام الجدولة الزمنية (CRON Jobs): كيف تجعل السكربت يعمل وأنت نائم خيار بسيط ومستقر. أما إذا أردت مزامنة فورية بعد كل push، فاستخدم Webhook.
التمييز بين النموذجين مهم: API polling يعني أن سكربتك يسأل كل فترة، بينما Webhook يعني أن GitHub يرسل الإشعار عند وقوع الحدث. ويمكنك التوسع في هذا المفهوم عبر الفرق بين الـ API والـ Webhook: "لا تتصل بنا، نحن سنتصل بك".
التعامل مع الأخطاء والقيود التشغيلية
أي نظام جلب تلقائي يجب أن يتوقع الفشل. قد تواجه حد الطلبات، أو ملفاً محذوفاً، أو استجابة برمز 404، أو مشكلة مصادقة. من غير المقبول في بيئة إنتاج أن يتوقف التدفق بالكامل بسبب عنصر واحد.

أفضل ممارسات المعالجة:

راقب رموز الاستجابة مثل 200 و401 و403 و404.
أضف retry logic محدوداً.
استخدم تخزيناً مؤقتاً لتقليل استهلاك Rate Limit.
سجّل الأخطاء في ملف أو خدمة مراقبة.


إذا أردت التعمق في هذه الجوانب، راجع رموز الحالة (HTTP Status Codes): ماذا يخبرك السيرفر بـ 200 أو 404؟ وتحديد معدل الطلبات (Rate Limiting): كيف تتجنب الحظر من الخوادم.
كيف تجعل "Code Vault" مفيداً لأدسنس والزائر معاً؟
المشكلة في كثير من الصفحات البرمجية أنها تعرض كوداً خاماً بلا تفسير، وهذا يضعف القيمة التحريرية. لكي يكون المحتوى مؤهلاً أكثر من منظور الجودة، يجب أن ترفق مع كل كود وصفاً عملياً: ما المشكلة التي يحلها؟ متى تستخدمه؟ ما المتطلبات؟ وما المخاطر؟
احرص أيضاً على إضافة طبقات فائدة واضحة مثل: شروحات مختصرة، تصنيفات حسب اللغة، أمثلة مدخلات ومخرجات، وسياق ربط مع أدوات الأتمتة. ويمكنك الإشارة إلى مفاهيم مثل لماذا نحتاج الأتمتة؟ كيف توفر الشركات آلاف الساعات عندما تشرح أثر إعادة استخدام الأكواد على الإنتاجية.
خاتمة
إنشاء Code Vault خاص بك ليس مشروع تجميلي، بل بنية نشر ذكية توحّد بين التطوير والمحتوى. أنت لا تجلب الملفات فقط، بل تبني خط إنتاج معرفي يبدأ من GitHub وينتهي بصفحات تعليمية موثوقة داخل موقعك.
كلما كان التدفق منظماً، وآلية الأمان محكمة، والشرح التحريري عميقاً، زادت قيمة مدونتك لدى القارئ ومحركات البحث معاً. والنتيجة النهائية هي مكتبة أكواد حية، قابلة للتحديث، ومصممة لتخدم التعلم الحقيقي لا مجرد العرض السطحي.