إنشاء المحتوى

يستخدم Xingluo Astro Content Collections لإدارة المحتوى، ويدعم Markdown (.md) و MDX (.mdx، يتطلب features.mdx).

مجموعات المحتوى

تم تعريف مجموعتين في src/content.config.ts:

المجموعة	الدليل	الغرض
`posts`	`src/content/posts/`	مقالات المدونة
`pages`	`src/content/pages/`	الصفحات الثابتة (مثل صفحة حول)

اتفاقيات تسمية الملفات:

الملفات أو الدلائل التي تبدأ بـ _ يتم تجاهلها (مفيد للمسودات)
عند تمكين MDX، يتم جمع **/*.{md,mdx}؛ وإلا فقط **/*.md
عناوين URL للمقالات تُشتق من مسار الملف (انظر قسم التوجيه في نظرة عامة على الهندسة)

Frontmatter المقالات

الحقول الكاملة لمجموعة posts:

markdown
---
title: "عنوان المقال" # مطلوب
pubDatetime: 2026-06-19T10:00:00+08:00 # مطلوب، وقت النشر
modDatetime: 2026-06-20T10:00:00+08:00 # اختياري، وقت التحديث
description: "الملخص، يُستخدم لـ SEO والقوائم" # مطلوب
tags: ["Astro", "مدونة"] # اختياري، الافتراضي ["others"]
featured: true # اختياري، مميز (يظهر في الصفحة الرئيسية)
draft: false # اختياري، المسودات لا تُنشر
author: "Xingluo" # اختياري، الافتراضي site.author
ogImage: "./cover.png" # اختياري، صورة OG (استيراد الصورة أو مسار نصي)
canonicalURL: "https://..." # اختياري، رابط canonical
hideEditPost: false # اختياري، إخفاء رابط التحرير
timezone: "Asia/Shanghai" # اختياري، تجاوز منطقة زمنية للموقع
---

مرجع الحقول

الحقل	النوع	الافتراضي	الملاحظات
`title`	string	مطلوب	عنوان المقال
`pubDatetime`	date	مطلوب	وقت النشر، ISO 8601
`modDatetime`	date	—	وقت التحديث؛ يُعرض مع وقت النشر
`description`	string	مطلوب	الملخص، يُستخدم في meta و RSS وبطاقات القوائم
`tags`	string[]	`["others"]`	مصفوفة الوسوم؛ يتم إنشاء صفحات الوسوم تلقائيًا
`featured`	boolean	—	يُعرض في قسم “مميز” في الصفحة الرئيسية
`draft`	boolean	—	مسودة؛ يتم تصفيتها في بناء الإنتاج (مرئية في التطوير)
`author`	string	`site.author`	اسم المؤلف
`ogImage`	image \| string	—	صورة OG؛ `image()` تمر عبر خط أنابيب أصول Astro، والنص هو مسار `public/` أو رابط خارجي
`canonicalURL`	string	—	رابط canonical، يتجاوز الافتراضي (انظر تحسين محركات البحث)
`hideEditPost`	boolean	—	إخفاء رابط التحرير لهذا المقال
`timezone`	string	`site.timezone`	تجاوز المنطقة الزمنية المعروضة لهذا المقال
`locale`	string	`site.lang`	اللغة التي كُتب بها المقال، مثلاً `"en"`، `"ja"`. الافتراضي لغة الموقع عند عدم التعيين
`translationKey`	string	—	مفتاح مجموعة الترجمة: المقالات التي تشارك نفس المفتاح هي ترجمات لبعضها البعض. المقالات بدون مفتاح مستقلة
`category`	string	—	تصنيف المقال (قيمة واحدة)، يُنشئ صفحة `/categories/<slug>/`؛ عدم التعيين يعني عدم وجود تصنيف

الترجمة على مستوى المحتوى

استخدم حقلي frontmatter locale و translationKey لإنشاء إصدارات متعددة اللغات لمقالاتك:

ضع المقال باللغة الافتراضية في src/content/posts/<slug>.md
ضع الترجمات في أدلة فرعية للغة: src/content/posts/<locale>/<slug>.md (مثل en/welcome.md)
عيّن locale إلى لغة الترجمة و translationKey إلى نفس قيمة الأصل

تقوم طبقة التوجيه تلقائيًا بحل الترجمة الصحيحة لكل لغة وإزالة التكرار في القوائم — نفس المقال بلغات مختلفة يُظهر بطاقة واحدة فقط لكل لغة. المقالات بدون ترجمة تعود إلى المحتوى الأصلي. انظر التدويل.

النشر المجدول

يتم تصفية المقالات ذات الطوابع الزمنية المستقبلية في الإنتاج باستخدام تسامح scheduledPostMargin: إذا كان pubDatetime ضمن نافذة التسامح (افتراضي 15 دقيقة) من الوقت الحالي، يتم التعامل مع المقال كمنشور. في التطوير، جميع المقالات غير المسودة مرئية.

Frontmatter الصفحات الثابتة

مجموعة pages لها حقول أبسط:

markdown
---
title: "حول"
description: "حول هذا الموقع" # اختياري
ogImage: "default-og.jpg" # اختياري، نص فقط
canonicalURL: "https://..." # اختياري
---

يتم جلب صفحة “حول” عبر getEntry("pages", "about") ويتطلب إنشاء src/content/pages/about.md.

تحسينات Markdown

يأتي Xingluo مزودًا بالإضافات التالية remark / rehype (انظر astro.config.ts):

جدول المحتويات

remark-toc يُنشئ جدول المحتويات تلقائيًا؛ remark-collapse يطويه افتراضيًا. أدرج العنصر النائب في المقال:

markdown
## Table of contents

(يتم ملء جدول المحتويات تلقائيًا هنا)

التنبيهات (Callouts)

rehype-callouts يدعم التنبيهات على نمط Obsidian:

markdown
> [!NOTE]
> محتوى الملاحظة

> [!WARNING]
> محتوى التحذير

> [!TIP]
> محتوى النصيحة

الأنواع المدعومة: NOTE، TIP، INFO، WARNING، DANGER، SUCCESS، QUESTION، FAILURE والمزيد.

تمييز الكود

Shiki ذو النسق المزدوج (فاتح min-light، داكن night-owl) يدعم:

تمييز السطور: ```js {1,3-5}
تمييز الكلمات: ```js /word/
علامات الفرق: + / - في بداية السطر
تسميات أسماء الملفات: ```js file=src/index.ts أو filename=src/index.ts

example.jsjs
function hello() {
  console.log("hello"); // سطر مميز
}

الجداول

الجداول العريضة تُلف تلقائيًا في حاوية قابلة للتمرير أفقيًا (إضافة rehypeWrapTable)، مما يمنع الفائض على الشاشات الضيقة.

دعم MDX

عند تمكين features.mdx (افتراضي)، يمكنك استخدام ملفات .mdx للكتابة القائمة على المكونات.

المكونات المخصصة

مكونات MDX المدمجة في Xingluo موجودة في src/components/mdx/ ويتم استيرادها من مدخل موحد:

mdx
import { APlayer, DPlayer } from "@/components/mdx";

# مقالتي

<APlayer
  audio={[
    { name: "أغنية", artist: "فنان", url: "/audio.mp3", cover: "/cover.jpg" },
  ]}
/>

<DPlayer video={{ url: "/video.mp4", pic: "/cover.jpg" }} />

انظر مشغلات الوسائط للتفاصيل.

تعطيل MDX

عند ضبط features.mdx: false:

تكامل mdx() لا يُحمَّل
نمط glob لمجموعة المحتوى يطابق فقط *.md (ملفات .mdx الموجودة لا تُجمع)
مخرجات البناء لا تحتوي على وقت تشغيل MDX

وقت القراءة

يُعرض وقت القراءة المقدر تلقائيًا في صفحات تفاصيل المقال وبطاقات القوائم:

لغات CJK (zh-cn، ja، ko): تُحسب بعدد أحرف CJK، ~400 حرف في الدقيقة
اللغات الأخرى: تُحسب بعدد الكلمات (مفصولة بمسافات)، ~200 كلمة في الدقيقة
النتيجة تُقرَّب لأعلى، دقيقة واحدة كحد أدنى

قبل العد، يتم إزالة كتل الكود وعلامات HTML وعناوين URL لروابط Markdown والمحتوى غير النصي الآخر للحفاظ على التقدير قريبًا من حجم القراءة الفعلي. لا حاجة للتكوين.

المقالات ذات الصلة

يُعرض حتى مقالتين ذات صلة في أسفل صفحات تفاصيل المقال (بعد التنقل السابق/التالي):

مرتبة حسب عدد الوسوم المشتركة، تنازليًا
نفس الدرجة مرتبة حسب تاريخ النشر، تنازليًا (تفضيل المقالات الأحدث)
لا يتم عرض القسم عندما لا تشارك أي مقالة الوسوم
يتم تجاهله تلقائيًا بواسطة فهرس بحث Flexsearch

لا حاجة للتكوين.

الشريط الجانبي الثابت لجدول المحتويات

يظهر شريط جانبي ثابت لجدول المحتويات على الجانب الأيمن من صفحات تفاصيل المقال على الشاشات الكبيرة (≥1024px):

يتم إنشاؤه تلقائيًا من عناوين h2–h6 في المقال، ويُعرض كقائمة مسطحة ذات مسافات بادئة
تعكس المسافات البادئة عمق العنوان (h3 له مستوى إضافي من المسافة مقارنة بـ h2)
يتم تمييز القسم الحالي أثناء التمرير (IntersectionObserver)
يؤدي النقر على إدخال جدول المحتويات إلى التمرير بسلاسة إلى العنوان المقابل
مخفي على الشاشات الصغيرة (الجوال)، حيث يتوفر جدول المحتويات القابل للطي المضمن

يتم إنشاؤه من headings التي يعيدها render() في Astro — دون صيانة يدوية لجدول المحتويات من قبل المؤلف. يتعايش جدول المحتويات القابل للطي المضمن remark-toc (اكتب ## جدول المحتويات في مقالك) مع الشريط الجانبي للاستخدام على الشاشات الصغيرة.

التصنيفات

قم بتعيين تصنيف لمقال عبر حقل category في frontmatter (سلسلة نصية واحدة):

yaml
---
title: "مقالتي"
category: "دروس"
---

صفحة التصنيف موجودة في /categories/<slug>/؛ يتم تطبيع slug عبر slugifyStr (CJK محفوظ، لاتيني بأحرف صغيرة مع شرطات)
فهرس التصنيفات في /categories/ يسرد جميع التصنيفات
بطاقات المقالات وصفحات التفاصيل تظهر تلقائيًا رابط التصنيف (انقر للانتقال إلى صفحة التصنيف)
ينتمي المقال إلى تصنيف واحد على الأكثر (على عكس tags المتعددة)؛ المقالات بدون category لا تظهر في أي تصنيف
صفحات التصنيف تعيد استخدام posts.perPage للترقيم وتدعم مسارات المرآة متعددة اللغات (/en/categories/...)
تعطيل التصنيفات عبر features.showCategories: false (إزالة إدخال التنقل والصفحات، وتصفية خريطة الموقع)