نموذج المحتوى

الملفات

كل مستند عبارة عن ملف .mdx (أو .md) واحد في مجلد النوع:

content/
  blog/
    hello-world.mdx        → slug "hello-world"
    _redirects.json        → redirect rules for this type (optional)
  authors/
    jane.mdx               → slug "jane"

• يكون اسم الملف هو الرابط الإنجليزي (slug). تُكتب الروابط بأحرف صغيرة مفصولة بشرطات (kebab-case).
• توجد الملفات الإنجليزية فقط على القرص، بينما تُحفظ النسخ المترجمة في قاعدة بيانات SQLite.
• يتم تجاهل الملفات التي يبدأ اسمها بحرف _ أو حرف كبير (مثل PUBLISHING.md)، مما يتيح لك الاحتفاظ بالملاحظات بجوار المحتوى الخاص بك.

البيانات الوصفية (Frontmatter)

تُكتب البيانات الوصفية بتنسيق YAML، ويتم التحقق من صحتها وفقاً لمخطط Zod الخاص بالنوع:

---
title: "Hello, world"
description: "A long enough description for the schema."
author: jane
publishedAt: "2026-01-15"
updatedAt: "2026-02-01"
---

Body is MDX.

يتبع التحقق من صحة المخطط مخطط Zod الخاص بك. عند استخدام z.object عادي، تُحذف المفاتيح غير المعروفة بصمت. استخدم .strict() إذا كنت تريد أن تؤدي الأخطاء الإملائية في أسماء الحقول إلى فشل عملية التحقق.

حقول البيانات الوصفية المدمجة

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

الحقل	النوع	الوصف
publishedAt	تاريخ ISO	تاريخ النشر.
updatedAt	تاريخ ISO	تاريخ آخر تحديث مهم. الافتراضي هو publishedAt. يُستخدم في خريطة الموقع كـ lastModified.
noindex	قيمة منطقية	الاستبعاد من خريطة الموقع، وعرضها كعلامة وصفية لبرامج الزحف (robots) في صفحاتك.
canonicalPath	نص	تجاوز مسار URL الأساسي يدوياً.

ترث المستندات المترجمة publishedAt و updatedAt و noindex و canonicalPath من المستند الإنجليزي الأصلي، ولا يمكن للمترجمين تغييرها.

يحمل كل مستند محمل أيضاً slug و enSlug (الرابط الإنجليزي الأصلي الذي يطابق slug في المستندات الإنجليزية) و locale و frontmatter و content.

الأنواع بدون محتوى نصي (Bodyless types)

غالباً ما تكون المجموعات المرجعية فقط (أنواع مثل model أو category التي يكون مخططها هيكلياً بالكامل) بدون محتوى MDX على الإطلاق. يمكنك التصريح بـ body: false في النوع لتوضيح ذلك:

defineContentType({
  id: "model",
  contentDir: "models",
  schema: modelSchema,
  body: false, // entries are frontmatter-only
});

القيمة الافتراضية هي body: true، لذا فإن هذا متوافق تماماً مع الإصدارات السابقة. في النوع body: false، يُعد أي محتوى نصي غير المسافات الفارغة خطأ في التحقق، ويتخطى المحمل تحليل MDX، ولا تُصدر عمليات التصدير الثابتة أي محتوى نصي. الأنواع التي لا تحتوي على أي محتوى نصي ولا تضم حقولاً قابلة للترجمة تُستبعد من جميع مسارات عمل الترجمة. أما النوع الذي لا يحتوي على محتوى نصي ولكنه يضم حقلاً قابلاً للترجمة فيبقى ضمن المهام المطلوبة باستخدام البيانات الوصفية فقط. راجع الترجمة لمعرفة قاعدة قابلية الترجمة.

ما وراء البيانات الوصفية

يمكن أن يقدم نص MDX ما هو أكثر من مجرد نصوص عادية:

• تقوم الرموز المضمنة بتضمين الروابط وعناوين URL للأصول والنصوص غير القابلة للترجمة مباشرة في النص، وتُحلل لكل لغة وقت القراءة.
• تُفحص الأصول المُعلن عنها باستخدام field.asset() على القرص وتُحول إلى عناوين URL عامة وقت التحميل.

عمليات إعادة التوجيه: _redirects.json

لكل مجلد نوع محتوى، أضف ملف _redirects.json اختيارياً للإعلان عن عمليات ترحيل الروابط والمستندات الملغاة. تظل عمليات إعادة التوجيه فعالة بعد حذف مصدر MDX. تُوسع الروابط المصدرية المترجمة تلقائياً من SQLite.

{
  "redirects": [
    { "from": "hello-world", "toSlug": "hello-scribe" },
    { "from": ["old-a", "old-b"], "toSlug": "hello-scribe" },
    { "from": "moved-post", "toType": "glossary", "toSlug": "virtual-try-on" },
    { "from": "retired-page", "toUrl": "/pricing" },
    { "from": "retired-ext", "toUrl": "https://example.com/app" }
  ]
}

يوجد ثلاثة أنواع لإعادة التوجيه (هدف واحد بالضبط لكل إدخال):

النوع	الحقول	الوصف
نفس النوع	toSlug	الرابط الإنجليزي المستهدف في نفس نوع المحتوى. يُبنى عنوان URL من path الخاص بهذا النوع، ويُخصص لكل لغة.
عبر الأنواع	toType + toSlug	الرابط الإنجليزي المستهدف في نوع محتوى آخر قابل للتوجيه (يجب أن يحتوي على path).
أي مكان	toUrl	مسار نسبي لنفس الموقع أو عنوان URL خارجي مطلق، متطابق لجميع اللغات.

• from: الرابط الإنجليزي (slug) فقط. تُستخرج روابط المصدر المترجمة من SQLite.
• قيمة permanent الاختيارية (الافتراضي هو true).

لإلغاء أو إعادة تسمية مستند، أضف إدخالاً إلى _redirects.json، ثم احذف (أو أعد تسمية) ملف MDX المصدر، وشغّل scribe validate وأعد البناء. يتم إصدار قواعد إعادة التوجيه بواسطة buildAllContentRedirects() لتكوين الخادم الوكيل أو إطار العمل الخاص بك.

التحقق (Validation)

scribe validate

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

وعلى مستوى المشروع بأكمله يتحقق أيضاً من سلامة العلاقات (علاقة مطلوبة مفقودة تعني خطأ، وعلاقة اختيارية مفقودة تعني تحذيراً)، وقواعد _redirects.json (أهداف صالحة، وعدم وجود مصادر مكررة، وعدم وجود سلاسل إعادة توجيه)، وقواعد لاحقات الروابط المترجمة، وحقول الأصول المُعلن عنها (وجود الملف، و formats، و maxKB)، والرموز المضمنة في النص (العلامات المشوهة، والعلاقات المفقودة، و :href للأنواع غير القابلة للتوجيه، ومفاتيح vars المفقودة، وملفات الأصول المفقودة)، وأنواع body: false التي لا تزال تحمل محتوى نصياً، وأصول الصور المفقودة عند تعيين مجلد الأصول، وتواجد قاعدة بيانات الترجمة.

يكون رمز الخروج غير صفري عند العثور على أي خطأ. قم بتشغيله قبل عملية البناء الخاصة بك:

{
  "scripts": {
    "build": "scribe validate && <your framework build>"
  }
}