f5xc-docs-tools

يتحقق إضافة f5xc-docs-tools من ملفات محتوى MDX لخط أنابيب توثيق f5-sales-demo. يكتشف المشكلات الشائعة التي تتسبب في فشل البناء قبل وصولها إلى CI، بما في ذلك أحرف JSX غير المُعالجة، والاستيرادات غير الصالحة، ومراجع الصور المعطلة، والبيانات الوصفية الأمامية غير المكتملة.

v1.1.2 الإنتاجية

التثبيت

/plugin install f5xc-docs-tools@f5-sales-demo-marketplace

المهارات

mdx-content-reviewer

تُفعَّل هذه المهارة تلقائيًا عندما يكتشف Claude أنك تعمل مع ملفات MDX في مستودع محتوى f5-sales-demo. تُجري سبعة فحوصات للتحقق:

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

يتحقق من الحقول المطلوبة مثل title وsidebar.order. يجب أن تتضمن صفحات البداية حقول hero وtemplate: splash.

مشكلات بناء جملة MDX

يكتشف أحرف < غير المُعالجة والأقواس المتعرجة \{ \} غير المُهرَّبة التي تُعطل تحليل MDX.

التحقق من الاستيرادات

يتحقق من الاستيرادات مقابل قائمة مسموح بها من مكونات Starlight المدمجة ومكونات قالب f5-sales-demo.

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

يتحقق من الخصائص المطلوبة للمكونات مثل Screenshot وAside وCode وLinkCard وCard وBadge.

مراجع الصور

يتحقق من وجود الصور المُشار إليها في دليل docs/images/.

فحوصات البنية

يتأكد من وجود docs/index.mdx وأن أدلة الصور لا تحتوي على ملفات MDX شاردة.

التصديرات وكتل الكود

يتحقق من أن المتغيرات المستخدمة في خصائص code لمكون Code لها تصديرات مطابقة.

سلوك تحديد النطاق

تحدد المهارة نطاق مراجعتها بذكاء:

إذا كانت هناك تغييرات غير مُلتزم بها أو مُعدة في ملفات docs/**/*.mdx، تتم مراجعة تلك الملفات فقط
وإلا، تتم مراجعة جميع ملفات docs/**/*.mdx

تنسيق المخرجات

تُجمَّع النتائج حسب الخطورة:

خطأ — سيتسبب في فشل البناء؛ يجب إصلاحه قبل الدمج
تحذير — مشكلات محتملة يجب معالجتها
معلومات — اقتراحات وأفضل الممارسات

تتضمن كل نتيجة مسار الملف ورقم السطر ووصفًا للمشكلة.

الأوامر

/review-mdx

/f5xc-docs-tools:review-mdx [path-or-glob]

يُشغِّل مهارة mdx-content-reviewer عند الطلب.

المعاملات:

المعامل	مطلوب	الوصف
`path-or-glob`	لا	مسار ملف أو نمط glob لتحديد نطاق المراجعة. الافتراضي هو جميع ملفات `docs/*/.mdx`.

أمثلة:

# مراجعة جميع ملفات MDX في docs/
/f5xc-docs-tools:review-mdx

# مراجعة ملف محدد
/f5xc-docs-tools:review-mdx docs/getting-started.mdx

# مراجعة الملفات المطابقة لنمط glob
/f5xc-docs-tools:review-mdx docs/guides/*.mdx

المخرجات: سطر ملخص في النهاية يُبلِّغ عن إجمالي الملفات المُراجعة وعدد النتائج حسب الخطورة.

الاستيرادات المسموح بها

تتحقق الإضافة من الاستيرادات مقابل هذه المصادر:

مكونات Starlight المدمجة (@astrojs/starlight/components):

Aside Badge Card CardGrid Code FileTree Icon LinkCard Steps TabItem Tabs

مكونات قالب f5-sales-demo (@f5-sales-demo/docs-theme/components/):

Banner Icon LinkCard Screenshot

مرجع سريع للمكونات

المكون	الخصائص المطلوبة	الخصائص الاختيارية
Screenshot	`alt` + واحدة على الأقل من `light` أو `dark`	—
Aside	`type`	`title`
Code	`code`, `lang`	`title`, `frame`, `mark`, `ins`, `del`
LinkCard (القالب)	`title`, `href`	`description`, `icon`
Card	`title`	`icon`
Badge	`text`	`variant`
Steps	—	—
Tabs / TabItem	TabItem: `label`	—
CardGrid	—	—
FileTree	—	—

مشكلات MDX الشائعة

المشكلات الشائعة التي تكتشفها الإضافة:

المشكلة	السبب	الحل
`<` غير مُعالج	يُفسره MDX كوسم JSX	استخدم `&lt;` أو كود مُضمَّن أو أعد الصياغة
`\{` `\}` غير مُهرَّب	يُعامله MDX كتعبير JSX	استخدم كودًا مُضمَّنًا أو هرِّبه بـ `\` أو استخدم كتلة كود
أقواس متعرجة في أسماء الملفات	لا يستطيع Astro معالجة الملف	لا تستخدم `\{` أو `\}` أبدًا في أسماء ملفات `.mdx`