توثيق المحتوى

نظرة عامة

Zubd.io موقع Astro ستاتيك. يُخزَّن المحتوى كملفات MDX (Markdown + JSX) داخل src/content/products/ وsrc/content/articles/. لكل نوع من المحتوى مخطط Zod يتحقق من الـ frontmatter وقت البناء — إذا كان حقل مطلوب مفقوداً أو خاطئاً، يتوقف البناء برسالة خطأ واضحة.

كل محتوى موجود في ملفين: أحدهما في en/ والآخر في ar/. يجب أن تحمل كلتاهما نفس قيمة handle (التي يجب أن تطابق اسم الملف أيضاً).

القاعدة الذهبية: اسم الملف = حقل handle = متطابق عبر النسختين EN و AR. مثال: cerave-moisturizing-cream.mdx في كلا المجلدَين en/ وar/، وكلاهما يحمل handle: "cerave-moisturizing-cream".

مخطط المنتج

مسار الملف: src/content/products/ar/{handle}.mdx

الحقل	النوع	مطلوب	الوصف
`title`	string	✅	اسم عرض المنتج
`handle`	string	✅	رابط URL — يجب مطابقة اسم الملف، متطابق عبر اللغات
`locale`	"en" \| "ar"	✅	لغة هذا الملف
`brand`	string	✅	اسم العلامة التجارية
`model`	string	—	موديل/نسخة المنتج
`category`	string	✅	slug التصنيف — يُنشئ صفحة التصنيف تلقائياً
`subcategory`	string	—	تصنيف فرعي اختياري
`tags`	string[]	—	وسوم للبحث والتصفية
`image`	string (URL)	✅	صورة المنتج — استخدم رابط Unsplash أو /images/products/
`imageAlt`	string	✅	وصف بديل للصورة
`gallery`	string[]	—	روابط صور إضافية (للمعرض)
`rating`	0–5 float	✅	التقييم الإجمالي (مثال: 4.7)
`reviewCount`	integer	—	عدد المراجعات
`affiliateUrl`	URL string	✅	رابط الإحالة الكامل — يحصل على rel="nofollow sponsored"
`affiliateLabel`	string	—	نص زر الشراء (افتراضي: "اشترِ الآن")
`price`	string	—	نص السعر المعروض (مثال: "$24.99")
`priceUpdated`	ISO date	—	تاريخ آخر التحقق من السعر
`metaDescription`	string ≤320	✅	وصف SEO
`pros`	string[]	✅	قائمة الإيجابيات
`cons`	string[]	✅	قائمة السلبيات
`userReviews`	Review[]	—	انظر كائن المراجعة أدناه
`publishedAt`	ISO date	✅	تاريخ النشر
`updatedAt`	ISO date	—	تاريخ آخر تحديث
`draft`	boolean	—	true = مخفي من البناء (افتراضي: false)

كائن مراجعة المستخدم

الحقل	النوع	الوصف
`author`	string	اسم المراجع
`rating`	0–5 float	تقييم المراجع بالنجوم
`date`	ISO date	تاريخ المراجعة
`text`	string	نص المراجعة
`source`	"amazon" \| "google" \| "manual"	مصدر المراجعة

قالب المنتج الكامل

---
title: "اسم المنتج"
handle: "product-name"
locale: "ar"
brand: "العلامة التجارية"
model: "الموديل"
category: "category-slug"
tags: ["وسم1", "وسم2"]
image: "https://images.unsplash.com/photo-XXXXX?w=480&auto=format&fit=crop&q=80"
imageAlt: "وصف بديل للصورة"
rating: 4.5
reviewCount: 120
affiliateUrl: "https://amzn.to/XXXXXX"
affiliateLabel: "اشترِ من أمازون"
price: "$49.99"
priceUpdated: "2025-04-07"
metaDescription: "وصف قصير أقل من 160 حرف للـ SEO."
pros:
  - "الإيجابية الأولى"
  - "الإيجابية الثانية"
cons:
  - "السلبية الأولى"
userReviews:
  - author: "محمد أ."
    rating: 5
    date: "2025-03-01"
    text: "منتج رائع!"
    source: "amazon"
publishedAt: "2025-04-07"
draft: false
---

## نظرة عامة

نص مراجعتك بصيغة Markdown هنا...

مخطط المقال

مسار الملف: src/content/articles/ar/{handle}.mdx

الحقل	النوع	مطلوب	الوصف
`title`	string	✅	عنوان المقال
`handle`	string	✅	رابط URL — يجب مطابقة اسم الملف
`locale`	"en" \| "ar"	✅	لغة هذا الملف
`category`	string	✅	slug التصنيف
`subcategory`	string	—	تصنيف فرعي اختياري
`tags`	string[]	—	وسوم للاكتشاف
`heroImage`	string (URL)	✅	رابط صورة الهيرو
`heroImageAlt`	string	✅	النص البديل لصورة الهيرو
`excerpt`	string ≤300	✅	ملخص المقال في البطاقات
`featuredProducts`	string[]	✅	قائمة مرتبة بـ handle المنتجات (#1 أولاً)
`metaTitle`	string	—	عنوان SEO بديل
`metaDescription`	string ≤320	✅	وصف SEO
`author`	string	—	اسم الكاتب (افتراضي: "فريق تحرير زُبد")
`publishedAt`	ISO date	✅	تاريخ النشر
`updatedAt`	ISO date	—	تاريخ آخر تحديث رئيسي
`draft`	boolean	—	true = مخفي (افتراضي: false)

تلميح: featuredProducts هو الحقل الأساسي الذي يربط المقال ببطاقات المنتجات. أدرج قيم handle للمنتجات مرتبةً حسب التسلسل — #1 أولاً. يقوم مكوّن RankedProductList بجلبها وعرضها تلقائياً.

قالب المقال الكامل

---
title: "أفضل 10 [منتجات] لـ [حالة الاستخدام] (2025)"
handle: "top-10-products-use-case"
locale: "ar"
category: "category-slug"
tags: ["وسم1", "وسم2"]
heroImage: "https://images.unsplash.com/photo-XXXXX?w=1200&auto=format&fit=crop&q=80"
heroImageAlt: "النص البديل الوصفي لصورة الهيرو"
excerpt: "ملخص موجز لما يغطيه المقال (بحد أقصى 300 حرف)."
featuredProducts:
  - "product-handle-1"
  - "product-handle-2"
  - "product-handle-3"
metaTitle: "أفضل 10 [منتجات] لـ [حالة الاستخدام] (2025)"
metaDescription: "وصف SEO أقل من 160 حرف."
author: "فريق تحرير زُبد"
publishedAt: "2025-04-07"
draft: false
---

## لماذا تثق بهذه القائمة؟

فقرة المنهجية...

## ما الذي تبحث عنه؟

معايير الشراء الرئيسية...

التصنيفات

التصنيفات مشتقة تلقائياً من حقل category في frontmatter المقال. لا يوجد ملف تصنيف منفصل لإنشائه. عند نشر مقال بـ category: "fitness"، تُبنى صفحة /ar/categories/fitness تلقائياً وتعرض جميع المقالات في ذلك التصنيف.

لإضافة تصنيف جديد، استخدم قيمة category جديدة في frontmatter المقال. لإضافة تسمية مقروءة له، أضف إدخالاً إلى src/lib/utils.ts في دالة getCategoryLabel():

// src/lib/utils.ts → getCategoryLabel()
fitness: { en: 'Fitness', ar: 'اللياقة البدنية' },
food:    { en: 'Food & Kitchen', ar: 'الطعام والمطبخ' },
// أضف تصنيفك الجديد هنا:

الصور (Unsplash)

تستخدم جميع صور المنتجات والمقالات روابط Unsplash مباشرةً — لا حاجة لاستضافة الصور. استخدم هذا التنسيق:

https://images.unsplash.com/photo-{PHOTO_ID}?w=1200&auto=format&fit=crop&q=80

الأحجام الشائعة:

هيرو المقال: ?w=1200&h=630&fit=crop
صورة المنتج: ?w=480&h=480&fit=crop
صورة OG: ?w=1200&h=630&fit=crop

ابحث عن الصور على unsplash.com — انسخ معرف الصورة من الرابط.

سير عمل النشر

أنشئ src/content/products/en/your-product.mdx
أنشئ src/content/products/ar/your-product.mdx (نفس اسم الملف)
أضف handle المنتج إلى قائمة featuredProducts في المقال
أنشئ src/content/articles/en/your-article.mdx
أنشئ src/content/articles/ar/your-article.mdx
شغّل npm run build — يتحقق Zod من جميع frontmatter
ادفع إلى main → ينشر Cloudflare Pages تلقائياً

التحقق من البناء: إذا كان أي حقل في frontmatter غير صالح، يتوقف البناء برسالة خطأ واضحة. هذا يمنع وصول محتوى مكسور إلى الإنتاج. استخدم draft: true لحفظ العمل الجاري دون نشر.

بنية الروابط

الصفحة	رابط EN	رابط AR
الرئيسية	/en	/ar
مقال	/en/articles/{handle}	/ar/articles/{handle}
منتج	/en/products/{handle}	/ar/products/{handle}
تصنيف	/en/categories/{category}	/ar/categories/{category}
الخصوصية	/en/privacy	/ar/privacy
التواصل	/en/contact	/ar/contact
التوثيق	/en/docs	/ar/docs
Sitemap	/sitemap-index.xml
llms.txt	/llms.txt