Docusaurus

تعيد شرح خطوات تشغيل مشروعك لكل عضو جديد، وتوزع التعليمات بين README ورسائل المحادثة وملفات قديمة. وعندما يتغير إصدار المنتج، لا يعود واضحًا أي شرح يناسبه. يساعدك Docusaurus على تحويل هذا المحتوى إلى موقع توثيق منظم: تكتب ملفات نصية، تراجع تعديلاتها مع الفريق، ثم تبني صفحات قابلة للاستضافة. قيمته ليست كتابة الشرح بدلًا منك، بل إعطاؤه مكانًا ومسار قراءة ولغة وإصدارًا واضحًا.

🧭 ما هو Docusaurus؟

Docusaurus مولّد مواقع مفتوح المصدر من Meta والمساهمين، يركز على مواقع التوثيق. يعتمد على React، ويقبل Markdown وMDX؛ الأخير يتيح مزج النص مع مكونات React عند الحاجة إلى مثال تفاعلي أو عنصر مخصص. لا تحتاج إلى كتابة مكون لتأليف كل صفحة: يمكنك البدء بعناوين وفقرات وروابط وكتل أوامر عادية.

يقرأ ملفات المحتوى وإعدادات الموقع، ثم يولّد ملفات ثابتة داخل build/. يمكنك معاينتها محليًا ونشرها على استضافة ملفات ثابتة. لا يلزم أن تضيف قاعدة بيانات لمجرد عرض دليل، لكن خدمات مثل تسجيل الدخول والبحث الخارجي والتحليلات ليست نتيجة مضمونة من وجود ملفات HTML؛ كل إضافة تغير التكلفة ومسار البيانات ومسؤولية التشغيل.

رسم توضيحي أصلي، وليس لقطة واجهة أو نتيجة بناء منفذ. النشر إلى الاستضافة خطوة منفصلة عن بناء الملفات.

🎯 كيف ستفيدك الأداة عمليًا؟

تناسب مطورًا أو فريقًا صغيرًا يريد دليل تشغيل منتج أو مكتبة أو API، ويمكنه التعامل مع ملفات المشروع وGit. مثلًا، ضع شرح الإعداد والصلاحيات وحل المشكلات في موقع واحد، بدل أن يطلب كل موظف رابط الرسالة الصحيحة. وعند تغيير طريقة الإعداد، يمكن أن يتضمن طلب مراجعة الكود تعديل صفحة الدليل أيضًا. هذا مسار عمل مقترح، وليس مزامنة سحرية بين الكود والشرح.

القيمة المضافة هي فصل تأليف المعرفة عن بناء التنقل والتصميم من الصفر، مع إمكان حفظ نسخ مختلفة عندما يحتاج مستخدمو المنتج فعلًا إلى شروح مختلفة. إن كان لديك README قصير يكفي القارئ، فلا تحتاج إلى نقل المشروع كله إلى موقع جديد. وإذا كان فريقك يريد التحرير المباشر المتزامن من المتصفح بلا Git أو بناء، فقد تكون أداة مستندات تعاونية أبسط.

🌟 الميزات الرئيسية وطريقة استخدامها

1. قائمة جانبية من هيكل الملفات (Autogenerated Sidebar)

يمكن بناء قائمة التنقل تلقائيًا من مجلد التوثيق: يصبح المجلد فئة، وتصبح الملفات روابط صفحات. يفيدك هذا عندما تكبر الأدلة وتريد إضافة صفحة إلى مكان مفهوم دون بناء قائمة روابط يدويًا في كل مرة.

• أين تضبطها: في sidebars.js، عبر عنصر نوعه autogenerated ومسار dirName بالنسبة إلى مجلد التوثيق.
• كيف تستخدمها: اجمع شروح المهمة الواحدة في مجلد، مثل docs/guides/، ثم اضبط التسميات والترتيب عند الحاجة. تدعم الصفحة sidebar_label وsidebar_position، ويمكن تخصيص الفئة عبر _category_.json.
• مثال توضيحي: يحتوي guides/ على setup.md وroles.md لخطوات التشغيل والصلاحيات. تظهر الصفحتان تحت فئة الأدلة، مع تسميات تكتبها أنت؛ أسماء الرسم التالية ليست ترجمات آلية لأسماء الملفات.
• القيد: الترتيب الافتراضي أبجدي داخل الجزء المولّد، وليس ترتيبًا تعليميًا يفهمه البرنامج. راجع المسار كما يراه القارئ. وقد يغيّر تعديل اسم الملف أو معرّفه رابطه الافتراضي؛ استخدم slug ثابتًا حيث تحتاج روابط مستقرة.

رسم لعلاقة الملفات بالتنقل، لا شكلًا مفترضًا لواجهة المنتج. يظل عنوان الصفحة ومحتواها وتسلسلها مسؤولية الكاتب.

2. نسخ توثيق تناسب إصدارات المنتج (Versioning)

عندما يحتاج مستخدم الإصدار القديم إلى تعليمات مختلفة، يمكنك حفظ لقطة من الدليل الحالي ثم مواصلة كتابة الشرح القادم. ينشئ أمر نسخ التوثيق مجلدًا مثل versioned_docs/version-1.0.0/ وملف قائمة جانبية للإصدار، ويضيف اسمه إلى versions.json. لا ينشئ فرع Git ولا يصدر تطبيقك.

• أين تضبطها: من سطر الأوامر داخل موقع التوثيق، ثم خيارات إضافة التوثيق وإعداد عنصر docsVersionDropdown في شريط التنقل إذا أردت قائمة اختيار الإصدارات.
• كيف تستخدمها: راجع الدليل أولًا، ثم احفظ نسخة عند اختلاف يستحق بقاء تعليمات مستقلة. اسم 1.0.0 في مثالنا إصدار افتراضي لمنتجك، وليس إصدار Docusaurus الذي نراجعه.
• مثال توضيحي: من داخل مشروع الدليل، ينشئ npm run docusaurus docs:version 1.0.0 لقطة باسم 1.0.0. ثم تغير شرح إنشاء مستخدم في docs/ للعمل القادم. لا تتغير النسخة المحفوظة تلقائيًا؛ إن أردت تصحيح خطأ فيها، عدّل ملفات نسختها أيضًا ثم أعد البناء والنشر. هذا تطبيق لنمط الأمر الرسمي، ولم ننفذه.
• القيد: current يعني الملفات الموجودة في docs/، وlatest يعني النسخة الافتراضية في التنقل؛ ليسا دائمًا الشيء نفسه. بعد بدء النسخ، تكون ملفات docs/ افتراضيًا تحت /docs/next/، بينما تُعرض أحدث نسخة محفوظة افتراضيًا تحت /docs/. هذه المسارات قابلة للضبط.

رسم بمثال افتراضي. لا تقطع نسخة لكل إصلاح صغير بلا حاجة؛ الوثائق الرسمية نفسها تحذر من زيادة زمن البناء وتعقيد الصيانة.

3. محتوى عربي وإنجليزي مع اتجاه RTL (Internationalization)

يمكن تعريف أكثر من لغة للموقع، ووضع محتوى مترجم لكل لغة. تدعم الأداة اتجاه العربية من اليمين إلى اليسار، وتوفر آلية لترجمة تسميات الواجهة. لكنها لا تترجم فقرات الدليل لمجرد إضافة ar إلى الإعدادات.

• أين تضبطها: حقل i18n في docusaurus.config.js، وملفات اللغة تحت i18n/ar/، وعنصر localeDropdown في إعداد شريط التنقل.
• كيف تستخدمها: اختر لغة افتراضية، وأضف اللغات الأخرى، ثم ترجم صفحات Markdown كاملة في المكان الصحيح. عندما تكون الإنجليزية هي الافتراضية، تكون ترجمة محتوى docs/ العربي تحت i18n/ar/docusaurus-plugin-content-docs/current/.
• مثال توضيحي: تقدم دليل تشغيل بالإنجليزية ودليلًا عربيًا مقابلًا، وتضبط direction: 'rtl' للعربية. عند بناء اللغتين معًا على نطاق واحد، تُنتج اللغة الافتراضية في build/ والعربية في build/ar/ بالإعداد الاعتيادي.
• القيد: خادم التطوير يبدأ لغة واحدة في المرة؛ يمكن معاينة العربية بالأمر npm run start -- --locale ar بعد إعدادها. لا يعني ذلك أن بناء الإنتاج لا يدعم اللغتين. وبناء لغة منفردة له افتراضات مختلفة لمسار النشر، فلا تخلط بينه وبين بناء جميع اللغات. راجع الروابط والصور المترجمة والصفحات القديمة في كل لغة.

رسم لمسارات مبسطة؛ علامة النقاط تختصر اسم الإضافة الموضح كاملًا في النص. العربية في الصور شرح مضاف، وليست إثباتًا بأن محتوى مشروعك سيُترجم تلقائيًا.

🪜 مثال عملي: دليل تشغيل منتج صغير

هذا مثال توضيحي لم ننفذه ولم ننشئ به موقعًا فعليًا. افترض أنك تجهز دليلًا لمنتج ويب فيه إعداد أولي وصلاحيات مستخدمين.

1. حدد ثلاث صفحات يحتاجها القارئ فعلًا: بدء الاستخدام، إدارة الصلاحيات، وحل مشكلات الدخول. لا تبدأ بنقل كل محادثات الفريق إلى الموقع.
2. أنشئ موقعًا تجريبيًا بالقالب classic كما في قسم التثبيت. اكتب الصفحات تحت docs/، واضبط عناوينها ووصفها وتسلسلها؛ واستخدم ملفات تجريبية بلا بيانات عملاء.
3. راجع القائمة الجانبية من الصفحة الأولى إلى الأخيرة. جرّب الروابط وكتل الأوامر والصور، واسأل هل يستطيع عضو جديد إكمال المهمة دون الرجوع إلى رسالة خاصة.
4. إذا احتجت اللغتين، أضف العربية إلى الإعدادات وترجم النسخ المقابلة، بما فيها النصوص داخل الصور. تغيير اتجاه الصفحة لا يعرب لقطة شاشة إنجليزية.
5. ابنِ الموقع وعاين ناتجه محليًا. تحقق من النسختين وروابطهما المباشرة قبل رفع مجلد build/ إلى استضافة تختارها. نجاح خادم التطوير ليس بديلًا عن فحص ناتج الإنتاج.
6. عندما يصدر منتجك ويتغير دليله لاحقًا، احفظ نسخة توثيق فقط إذا احتجت دعم المسارين. احتفظ بتصحيحات كل نسخة ولغة ضمن مراجعة واضحة.
7. اجعل تعديل الدليل جزءًا من مراجعة الميزة التالية. ويمكن استخدام Vale CLI لمراجعة أسلوب النص ضمن عملية مستقلة؛ Docusaurus لا يتحقق من صحة المعلومة التشغيلية بنفسه.

معيار النجاح هو أن يقرأ المستخدم تعليمات صحيحة لإصداره ولغته، ويستطيع فتح روابطها من الاستضافة، لا مجرد وجود موقع بتصميم جميل. لا ندعي في هذا المثال قياسًا لتوفير الوقت أو انخفاض عدد طلبات الدعم.

⚖️ ماذا تضيف مقارنة بالعمل اليدوي؟

⚙️ إعدادات مهمة قبل الاستخدام الحقيقي

راجع url وbaseUrl في ملف الإعدادات؛ الأول عنوان الموقع، والثاني مساره الأساسي، مثل / أو /handbook/. الإعداد غير المناسب قد يكسر الروابط أو الصور بعد النشر حتى لو عملت المعاينة المحلية. احتفظ بوصف واضح للصفحات وروابط ثابتة، وراجع بيانات البحث عند نشر موقعك؛ وجود إعدادات SEO افتراضية لا يضمن ترتيبًا في محركات البحث.

القالب classic يتضمن التوثيق وصفحات مخصصة ومدونة. وجود مجلد blog/ لا يلزمك استخدامه لدليل التشغيل؛ ابدأ بالجزء المطلوب فقط. ويمكن إضافة مكونات عبر MDX عند الحاجة، لكن اجعل النص العادي هو البداية: MDX أكثر صرامة من Markdown، وبعض رموز HTML والأقواس تحتاج صياغة مناسبة أو تهريبًا لتجنب أخطاء البناء.

🚀 التثبيت والبدء

تحققنا في 19 أكتوبر 2026 من الإصدار المستقر v3.10.2 المنشور في 10 يوليو 2026. يطلب ملف الحزمة والوثائق Node.js 20.0 فأعلى؛ هذا حد توافق، وليس توصية بتثبيت إصدار قديم غير مدعوم أمنيًا. اختر إصدار Node مدعومًا يلبي المتطلب. تحتاج أيضًا npm وبيئة طرفية تسمح بإنشاء ملفات المشروع وتنزيل الاعتماديات.

أمر الإنشاء الرسمي الموثق:

npx create-docusaurus@latest my-website classic

ينزل npx أداة الإنشاء ويشغل كودها، ثم تُنشأ ملفات مشروع واعتماديات. راجع الاسم والمصدر ولا تستخدم صلاحيات إدارية افتراضيًا. لم نشغل هذا الأمر أو أي تثبيت في الفحص. و@latest مرجع متغير؛ تحقق من الإصدارات التي أنشأها فعلًا، ولا تفترض أن تشغيله لاحقًا سيعيد الإصدار الموثق هنا.

للمعاينة، من داخل المشروع:

cd my-website
npm run start

ولبناء ناتج الإنتاج ومعاينته محليًا:

npm run build
npm run serve

راجع محتوى build/ ونتيجة المعاينة. لا نعرض سجل نجاح أو زمن بناء لأننا لم ننفذ التجربة. وعند الترقية، حافظ على توحيد إصدارات حزم @docusaurus/ المرتبطة كما يوضح دليل التثبيت، واحتفظ بملف القفل في مسار مراجعتك.

🔗 التوافق والتكامل والبحث

Docusaurus أداة مستقلة ضمن بيئة Node.js وReact، وليست إضافة لـDSH أو Claude Code أو Codex. يمكن حفظ محتواه مع كود مشروعك وتشغيل البناء ضمن CI، ثم استضافة الملفات ثابتة على خادمك أو خدمة تدعمها. وثقنا المتطلبات من الحزمة، ولم نختبر كل نظام تشغيل أو بيئة استضافة أو إضافة مجتمعية.

يدعم المشروع Algolia DocSearch رسميًا، بينما خيارات البحث المحلي وTypesense المذكورة في الدليل مجتمعية. لا تفترض أن تثبيت القالب يضيف بحثًا كاملًا بلا إعداد وفهرسة، ولا أن أي موقع مؤهل لخدمة مجانية. لم نفحص أسعار أو أهلية خدمة بحث خارجية لهذا المثال؛ قرار إضافتها يتطلب مراجعة شروطها ومكان الفهرس والبيانات التي تصل إليها.

💰 التكلفة والتشغيل المحلي

كود Docusaurus مرخص بـMIT، ولا يتطلب API مدفوعًا أو اشتراكًا في Docusaurus لبناء دليل ثابت. الترخيص لا يلغي تكلفة الاستضافة والنطاق والبناء أو صيانة الإضافات، ولا يمنح تلقائيًا حقوق إعادة نشر محتوى الآخرين. وثائق المشروع نفسها لها ترخيص منفصل عن كوده؛ النص والرسوم هنا شرح أصلي مع روابط للمراجع.

يمكن تأليف الدليل وبناؤه ومعاينته على جهازك. لكن التثبيت والترقيات تتصل بسجل الحزم، والنشر ينقل الناتج إلى المضيف الذي تختاره. وإذا أضفت بحثًا خارجيًا أو خطوطًا بعيدة أو تحليلات أو صورًا من مواقع أخرى، تتغير اتصالات القارئ وبياناته. لم ننفذ تدقيقًا شاملًا للشبكة أو جميع الاعتماديات؛ «محلي» لا يعني تلقائيًا «بلا اتصالات خارجية».

⚠️ الحدود ومتى لا تختاره

لا يحل Docusaurus محل إدارة المهام أو قاعدة معرفة تعاونية فورية أو نظام صلاحيات بيانات. يحتاج شخصًا مسؤولًا عن المحتوى والبناء والترقية، وتصبح تعددية الإصدارات واللغات عملًا مستمرًا، لا ميزة مجانية الصيانة. إذا نادرًا ما يتغير دليلك، ابدأ بنسخة واحدة بدل نسخ كثيرة متطابقة.

كما أن بناء صفحة بنجاح لا يثبت صحة خطواتها، ولا أن ترجمتها محدثة، ولا أن كل روابطها تعمل في إعداد المضيف. خصص مراجعة بشرية للمحتوى، وافحص الناتج المنشور. اختر حلًا أبسط إذا كان القارئ يحتاج صفحة واحدة، أو أداة مختلفة إذا كان الكاتب لا يستطيع التعامل مع ملفات المشروع ويريد التحرير المباشر فقط.

🔐 الخصوصية والصلاحيات

عامل ملفات المحتوى والإعدادات والإضافات ومكونات MDX كمصدر برمجي يحتاج مراجعة. دعم React في MDX يعني أنه ليس مجرد نص محايد؛ لا تدخل مكونات أو إضافات مجهولة إلى البناء. شغّل الإنشاء والبناء بحساب محدود، وراجع الاعتماديات، ولا تمنح مهمة البناء مفاتيح نشر لا تحتاجها.

كل ما تضعه في ملفات الموقع الثابتة يمكن أن يصل إلى زائر يستطيع تنزيلها. لا تضع مفاتيح سرية في المحتوى أو static/ أو customFields؛ تمرير قيمة بيئية إلى كود العميل لا يخفيها. ولا تعتبر إخفاء رابط من القائمة أو وجود مستودع Git خاص حماية لموقع نُشر علنًا. للأدلة الداخلية تحتاج حماية وصول حقيقية في طبقة الاستضافة أو بوابة مناسبة، مع مراجعة الصور والمرفقات والنسخ القديمة وفهرس البحث كذلك.

📚 المصادر وتاريخ التحقق

آخر تحقق: 19 أكتوبر 2026. الفحص للمستودع والوثائق وملفات الحزمة، وليس تجربة تثبيت أو نشر موقع Docusaurus. الصور ثمانية رسوم أصلية لأربع أفكار بنسختين عربية وإنجليزية، وليست لقطات للمنتج.

• المستودع الأصلي وREADME للإصدار والإصدار v3.10.2.
• التثبيت وملف الحزمة المثبت على الإصدار والترخيص.
• إنشاء صفحة والقائمة المولدة ونسخ التوثيق.
• تعدد اللغات وشرح إعداد الترجمة وMDX وReact.
• البناء والنشر وخيارات البحث. حُفظت مراجع ملفات هذه الوثائق على الوسم v3.10.2 في حزمة المصادر لتجنب الخلط مع توثيق التطوير.

أعاد GitHub وقت الفحص 66,524 نجمة و10,092 تفرعًا، وآخر دفع مسجل في 16 أكتوبر 2026. هذه مؤشرات شعبية ونشاط، وليست تقييمات مستخدمين أو شهادة جودة أو أمان. لم نوثق رقم تنزيلات أسبوعي؛ لا نستخدم صفرًا بدل المجهول.

قورنت الأداة مع Aider، مساعد برمجة طرفي مفتوح المصدر بترخيص Apache-2.0؛ يحرر الكود مع نماذج محلية أو سحابية، وتكلفة النموذج وخصوصيته قرار منفصل. أظهر مصدره آخر إصدار v0.86.0 في 9 أغسطس 2025 وآخر دفع في 22 مايو 2026، دون أن نستنتج من ذلك وحده أنه متوقف. اخترنا Docusaurus لمسار توثيق محدد ونشاط أحدث وتنويع المجال بعد Syncthing، لا لعدد النجوم. استُخدمت GitHub Topics وclaudeskills.info وdshmarket.com للاكتشاف، ثم اعتُمد المصدر الأصلي لإثبات الحقائق.