اختيارات تقنية لموقع التوثيق

تسجّل هذه الصفحة نتائج مسح أُجري في 2026-10-12 لأطر توثيق ثابتة شائعة، والقرار النهائي بشأن إطار موقع التوثيق الخاص بهذا المستودع.

سجل القرارات

التاريخ	القرار	السبب
2026-10-12 (يوم المسح)	اعتماد Astro Starlight، والانتقال من VitePress	Starlight لا يحتوي افتراضيًا على أي JavaScript من جانب العميل، وهو محايد تجاه الأطر، وهذا يتقارب أكثر ما يكون مع فلسفة «صفر JS في وقت التشغيل» الخاصة بهذا المستودع؛ وبعد إعادة كتابة الصفحات المرجعية الثلاث المدفوعة بالبيانات كمكوّنات Astro خالصة، أُزيلت تبعيات vue / vitepress / vite الثلاث بالكامل؛ وحد Node ≥22.12 مقبول
2026-10-12 (يوم المسح، حكم تمهيدي)	البقاء على VitePress	لم تكن فوائد الانتقال تغطي تكلفته آنذاك — جميع مواقع العائلة السبعة على VitePress، وكان موقع توثيق هذا المستودع قد اكتمل فعلًا. هذا الاستنتاج ألغاه قرار الانتقاء في اليوم نفسه، ويُحتفظ به أدناه كسجل تاريخي

تم الانتقال نفسه دفعة واحدة (أُقيم الهيكل العظمي لـ Astro واستُكمل نقل جميع الصفحات ضمن التزام واحد، تفاديًا لحالات وسيطة غير قابلة للبناء). وما زالت بقية مواقع العائلة تستخدم VitePress، وهذا المستودع لا يطلب توحيد الأطر على مستوى العائلة؛ وإذا اتحدت العائلة مستقبلًا على إطار واحد، فإن ممارسة Starlight في هذا المستودعتكون مرجعًا جاهزًا.

نتائج المسح (سجل تاريخي، استنادًا إلى بيانات 2026-10-12)

• لو بدأنا اليوم من الصفر، ودون قيد التوافق مع العائلة، فإن أفضل بديل هو Astro Starlight — الأداء، والحياد تجاه الأطر، وصفر JavaScript من جانب العميل افتراضيًا، وهو الأقرب إلى فلسفة «صفر JS في وقت التشغيل» الخاصة بهذا المستودع. (هذا الحكم هو ما أدى في النهاية إلى قرار الانتقال أعلاه.)
• توقفت VuePress فعليًا عن التطور، ولا يُنصح بأي مشروع جديد بتبنيها (آخر دفعة إلى المستودع تعود إلى 2024-08-07، ولا تزال النسخة v2 في مرحلة rc حتى الآن).
• الشيء الوحيد الذي كان يستحق المراقبة طويلًا قبل الانتقال هو VitePress 2.0 (كانت العلامة next تشير إلى 2.0.0-alpha.20، في مرحلة ألفا).

بيانات النشاط

تاريخ جمع البيانات: 2026-10-12. بيانات GitHub من api.github.com، وعدد تنزيلات npm هو إحصاء الأسبوع من 2026-10-04 إلى 10-10، وأرقام الإصدارات من وسوم dist-tags في registry.npmjs.org. أعداد النجوم (stars) تنمو مع الوقت، لذا انتبه إلى حداثة البيانات عند الاقتباس.

الإطار	البنية التقنية	نجوم GitHub	آخر دفعة للمستودع	تنزيلات npm الأسبوعية	أحدث نسخة مستقرة
VitePress	Vue 3 + Vite	18.4k	2026-10-11	1,305,159	1.6.4 (next: 2.0.0-alpha.20)
Docusaurus	React + MDX	66.5k	2026-10-10	1,504,459	3.10.2
Astro Starlight	Astro (محايد تجاه الأطر)	9.4k	2026-10-09	1,431,284 (أصل astro 7.22M)	astro 7.3.8 / starlight 0.42.6
docsify	تصيير في وقت التشغيل بـ JS	31.5k	2026-10-11	80,727	5.0.0
Nextra	Next.js + React	13.9k	2026-07-31	238,757	4.6.1
Fumadocs	Next.js + React	13.3k	2026-10-09	—	—
MkDocs Material	Python	27.6k	2026-10-02	PyPI، لا ينطبق	—
Sphinx	Python / RST	8.1k	2026-10-05	PyPI، لا ينطبق	—
VuePress	Vue + Webpack	22.7k	⚠️ 2024-08-07	71,177	1.9.10 (v2 متوقف عند 2.0.0-rc.31)
Dumi	Umi + React	3.8k	2026-09-14	20,163	2.4.50
Rspress	Rspack + React	2.3k	2026-10-10	19,631	1.47.2 (2.0 beta.21)

القراءة الأساسية: VitePress وDocusaurus هما المنافسان الوحيدان من الدرجة الأولى بتنزيلات شهرية تتجاوز المليون؛ وصعد Starlight على ظهر أصل astro (7.22 مليون) ليكون القطب الثالث؛ ورغم امتلاك VuePress 23 ألف نجمة، فلم يطرأ على المستودع أي التزام منذ أكثر من عامين، وقد حلّ VitePress محله فعلًا.

المزايا والعيوب حسب الفئة

الفئة الأولى: VitePress / Docusaurus / Astro Starlight

VitePress (كان يُستخدم في هذا المستودع قبل الانتقال؛ وما زالت بقية مواقع العائلة تستخدمه)

• المزايا: يمكن كتابة مكوّنات Vue أحادية الملف مباشرةً داخل markdown (وهو ما تعتمد عليه الصفحات المرجعية الثلاث في هذا المستودع: مرجع الرموز / عقود المكوّنات / الحالات الذهبية)؛ ومحمِّلات بيانات وقت البناء (*.data.ts) ملاءمة بطبيعتها لقراءة مصادر JSON الأصلية، مع إمكانية التحديث الساخن في وضع dev باستخدام watch على glob؛ وسرعة Vite dev عالية جدًا؛ والسمة الافتراضية جاهزة للاستخدام مباشرةً وتكاد تكون بلا إعدادات؛ والمجتمع والمواد الصينية غنية.
• العيوب: دعم MDX ضعيف (ليس ضمن منظومة MDX)؛ وتحتاج القدرات المؤسسية مثل توثيق الإصدارات المتعددة وi18n إلى بنائها بنفسك أو البحث عن إضافات؛ وعمق تخصيص السمات أقل من Docusaurus؛ والبحث يعتمد على فهرس محلي، وهو متوسط الأداء في المواقع الكبيرة.

Docusaurus (من إنتاج Meta، أكبر منظومة)

• المزايا: إضافة توثيق الإصدارات (تعايش نسخ متعددة من التوثيق) وi18n هما الأكثر نضجًا بين جميع الأطر؛ ومنظومة MDX ونظام الإضافات وحقن السمات (swizzle) مكتملة؛ وظهيرة Meta تضمن الصيانة طويلة الأمد.
• العيوب: تبعيات React الثقيلة وحجم JS كبير في منتجات البناء؛ وكثرة خيارات الإعداد تشكل عبئًا ذهنيًا؛ وخط بياناتها (دورة حياة loadContent) أكثر التفافًا للتعامل مع مصادر JSON الأصلية مقارنةً بمحمِّل VitePress؛ ولا يوجد سابقة في العائلة.

Astro Starlight (محايد تجاه الأطر، معيار للأداء؛ يُستخدم حاليًا في هذا المستودع)

• المزايا: صفر JavaScript من جانب العميل افتراضيًا، وهو الأكثر توافقًا مع فلسفة «صفر JS في وقت التشغيل» الخاصة بهذا المستودع؛ ومجموعات المحتوى (Content Collections) توفر طبقة بيانات آمنة من حيث الأنواع؛ ويمكن خلط المكوّنات من Vue / React / Svelte؛ ومنتجات البناء الأخف؛ وتجربة التوثيق التي تقدمها سمة Starlight ممتازة (الشريط الجانبي، تنقّل المراسي، i18n مدمج).
• العيوب: لا يزال Starlight في مرحلة 0.x (0.42.6)، وقد يشهد واجهة برمجية قابلة للكسر؛ ومجموعات المحتوى موجَّهة نحو المحتوى المبني على الملفات (md / mdx)، وقراءة مصادر JSON خارجية مثل tokens/*.json تستلزم تجاوز المجموعات والإحضار المباشر داخل صفحات .astro (وحلّ هذا المستودع ذلك بالفعل عبر استدعاء وحدات codegen مباشرةً من frontmatter)؛ ولا توجد سابقة في العائلة، وكان لابد من اجتياز ضوابط النشر / nginx / الشريط الجانبي منفردة (وقد اجتازها هذا المستودع فعلًا، راجع تعليمات النشر).

الفئة الثانية: Nextra / Rspress / Fumadocs / Dumi

• Nextra: منظومة Next.js، ودعم MDX قوي، وتوثيق جميل؛ لكنه مقيد بـ Next.js + React، ونموذج النشر (SSG / SSR / Edge) يختلف عن الاستضافة الثابتة عبر nginx المعتمدة في العائلة، واصطلاحات مجلدات المحتوى في v4 تختلف كثيرًا عن VitePress. لا دافع للانتقال.
• Rspress (من إنتاج web-infra-dev التابعة لـ ByteDance): أسرع بناءً (Rspack)، وملحوظ جدًا في مواقع التوثيق الكبيرة بمئات الصفحات؛ ومجتمع الصيانين الصينيين ودود. لكن منظومته / إضافاته الأقل عددًا (20 ألف تنزيل أسبوعيًا)، ولا توجد نمط قياسي لمحمِّلات البيانات — وهذا المستودع لديه 30 صفحة فقط، وتكلفة التعلم التي تُدفع من أجل السرعة لا مجال لاستخدامها.
• Fumadocs: الوافد الجديد الأسرع نموًا خلال العامين الماضيين (13.3 ألف نجمة، و 2 مشاكل مفتوحة فقط)، يعتمد Next.js + منظومة تصميم حديثة، وتجربة البحث / تبديل العرض جيدة. مقيد بـ Next.js كذلك، والمواد التوثيقية المحلية قليلة. يستحق المتابعة، ولا ينصح بإدخاله الآن.
• Dumi: صُمِّم لـ عروض المكوّنات (live demo، توليد جداول الخصائص تلقائيًا). وهذا المستودع مستودع رموز لوقت البناء، ولا يوجد لديه أي واجهة في وقت التشغيل لعرضها، فميزاته البيعية الأساسية غير صالحة للاستخدام إطلاقًا، وهو مقيد بـ Umi / React. مستبعد صراحةً.

الفئة الثالثة والحالات الخاصة

• MkDocs Material / Sphinx (منظومة Python): جودة التوثيق عالية جدًا، لكنه يتطلب سلسلة أدوات Python، وهي ليست في المنظومة نفسها التي يجمعها Node ≥20 + pnpm + TS في هذا المستودع، ولا يمكن إعادة استخدام أنواع TS ودوال التحميل الخاصة بـ codegen. مستبعد.
• docsify (تصيير في وقت التشغيل): لا يوجد بناء، يُجلب من CDN ويُستخدم مباشرةً، مناسب للوثائق الصغيرة «صفحة واحدة تنتشر بسرعة». لكنه لا يُولِّد HTML في وقت البناء (ضعف في SEO وبطء في تحميل الصفحة الأولى)، ولا يمكنه تشغيل محمِّل بيانات وقت البناء لإجراء تحقق schema (والصفحات المرجعية في هذا المستودع تعتمد تحديدًا على هذه القدرة). مستبعد.

مطابقة قيود هذا المستودع سطرًا بسطر

قيد / حاجة في هذا المستودع	VitePress	Docusaurus	Starlight	غيرها
توافق المواقع السبعة في العائلة (بادئة nginx / الشريط الجانبي / النشر)	✅ بقية مواقع العائلة تستخدمه	❌ يتطلب إعادة اجتياز الضوابط	✅ اجتازها هذا المستودع (اتفاقيات nginx الثلاثة ما زالت سارية، راجع تعليمات النشر)	❌
قراءة مصادر JSON الأصلية في وقت البناء لعرض الصفحات المرجعية	✅ محمِّل أصلي، تم تنفيذه	⚠️ يتطلب إضافة مخصصة	✅ تم تنفيذه (صفحات .astro تستدعي load / resolve الخاصة بـ codegen مباشرةً من frontmatter)	⚠️ أكثر تعقيدًا
لغة صينية واحدة، لا حاجة لـ i18n	✅	الميزة غير مستخدمة	✅	—
نصوص نثرية + جداول + كود دون عروض تفاعلية	✅	✅	✅	✅
طابع «صفر JS في وقت التشغيل»	⚠️ يوجد JS في وقت التشغيل (الموقع فقط، وليس ضمن نطاق الخط الأحمر)	❌ JS ثقيل	✅ صفر JS افتراضيًا	—
إعادة استخدام وحدات TS الخاصة بـ codegen (الأنواع / التحقق)	✅ تم التحقق منه (منذ vite ^5.4.21 يدعم SSR import.meta.dirname)	✅	✅ تم التحقق منه (يضم astro 7 أصل vite 8، ويدعم SSR import.meta.dirname)	✅

يُضاف معياران للقرار:

• الخط الأحمر «صفر JS في وقت التشغيل» ينظِّم منتجات dist/ الخاصة بـ codegen، لا موقع التوثيق. إن تشغيل الموقع لإطار في وقت التشغيل لا ينتهك أي خط أحمر — فهو معزول تمامًا عن dist/، ومنتجات بنائه خاضعة لـ .gitignore. ومع ذلك، بعد الانتقال إلى Starlight، صار الموقع نفسه أيضًا صفر JavaScript من جانب العميل افتراضيًا (مع تحميل تفاعلات قليلة عند الحاجة مثل البحث / تبديل السمة)، وهو أكثر اتساقًا مع روح الخط الأحمر.
• مزايا Docusaurus في توثيق الإصدارات وi18n غير مستخدمة في هذا المستودع: لغة صينية واحدة، ونسخة واحدة، والمحتوى يتبع codegen، ولا يوجد سيناريو «تعايش توثيق إصدار قديم من الرموز».

بنود المراقبة المستقبلية

1. Starlight 1.0: هذا المستودع مقيد حاليًا على ^0.42.6. وقد تشهد مرحلة 0.x تغييرات قابلة للكسر، وعند إصدار 1.0 الرسمي يُقيَّم مسار الترقية (سوف تسرد أدلة انتقال Starlight نقاط التغيير).
2. VitePress 2.0: يُقيَّم عند بلوغه مرحلة beta. وما زالت بقية مواقع العائلة على VitePress، والنقطة الرئيسية هي أداء البناء ومتابعة Vite 7.
3. إشارات إعادة الاختيار: توقف صيانة Starlight لمدة طويلة، أو قرار على مستوى العائلة بتوحيد إطار التوثيق (وحينها تكون ممارسة Starlight في هذا المستودع مرجعًا جاهزًا).