عرض ملف README للمشروع في Orbit

The Docs tab renders your repository's README inside KPanel, so the project's own documentation is one click from its deployments instead of in a browser tab someone has to go and find.

علامة التبويب Docs تعرض ملف README الخاص بمستودعك داخل KPanel، لذا تكون توثيق المشروع على بعد نقرة واحدة من عمليات النشر الخاصة به بدلاً من أن تكون في علامة تبويب متصفح يتعين على شخص ما البحث عنها.

حيث تقع علامة التبويب Docs

افتح Orbit، انقر فوق المشروع، واختر Docs ضمن مجموعة Overview في شريط علامات تبويب المشروع.

لا يوجد شيء لتكوينه. إذا كان المشروع يحتوي على مستودع متصل يحتوي على ملف README في جذره، ستعرض علامة التبويب محتواه.

الملف الذي يتم عرضه

يجلب Orbit ملف README من الفرع الافتراضي للمستودع المتصل.

على GitHub يحاول عدة أسماء تقليدية بالتتابع: README.md، readme.md، README.MD، README، و readme.txt، مع الأخذ بالأول الموجود. على GitLab و Bitbucket يبحث عن README.md.

يتم فحص جذر المستودع فقط. ملف README داخل مجلد فرعي، بما فيه مجلد جذر تطبيق monorepo، لن يتم التقاطه.

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

ما يتم عرضه

يتم عرض ملف README كـ markdown: العناوين والقوائم والجداول والروابط والأكواد المضمنة وكتل الأكواد المسيجة تعرض جميعها كما هو متوقع.

مسارات الصور النسبية داخل ملف README تشير إلى المستودع وليس إلى KPanel، لذا قد لا تتم معالجة الصور التي تعمل على موقع مزودك الخاص هنا. إذا كانت الصورة مهمة، استخدم عنوان URL مطلقاً.

حالات فارغة

حالتان تستبدل المحتوى عندما لا يكون هناك شيء لعرضه:

لا يوجد مستودع متصل، مع زر Connect repository. اتصل بأحدها أولاً: راجع Connecting a GitHub Repository، Connecting a GitLab Repository أو Connecting a Bitbucket Repository.
لم يتم العثور على README، يحثك على إضافة README.md إلى جذر مستودعك، مع رابط لإنشاء واحد لديك مزود الخدمة.

كلاهما ينقل خارجاً إلى المزود حتى تتمكن من التصرف على الفور، والعرض المأهول يحمل رابط View on للملف نفسه لعندما تريد تحريره.

كتابة ملف README يستحق العرض

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

هيكل يعمل:

ما هذا. فقرة واحدة. ما الذي يفعله المشروع ومن يخدمه.

تشغيله محلياً. الأوامر الدقيقة، بما فيها مدير الحزم. pnpm install && pnpm dev يفوق الفقرة التي تصف الشيء ذاته.

متغيرات البيئة. التي توجد وما كل واحدة منها. أبداً القيم: تلك تنتمي إلى متغيرات البيئة في المشروع وليس في ملف في المستودع. راجع Environment Variables in Orbit.

كيف يتم نشره. أي فرع هو الإنتاج، وما إذا كانت التسميات تنشر، وأي بوابات قيد التطبيق. أشر إلى علامة تبويب Orbit Deployment Pipeline بدلاً من تكرارها، لأن علامة التبويب لا يمكن أن تصبح قديمة وملف README الخاص بك يمكن.

كيفية الرجوع عنه. جملتان ورابط إلى Rolling Back a Deployment. هذا هو الشيء الذي يحتاجه الناس في أسوأ لحظات لهم، ويجب أن يكون حيث سينظرون.

من يملكه. فريق أو شخص. المشاريع تتجاوز الأشخاص الذين أعدوها.

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

إضافة شارة حالة مباشرة

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

افتح Settings وابحث عن بطاقة Status badge. يعرض معاينة مباشرة وثلاثة أزرار نسخ: عنوان URL الشارة، مقتطف markdown، ومقتطف HTML. الصق markdown في أعلى ملف README الخاص بك.

الشارة عبارة عن SVG صغير يقدم تقرير عن الحالة الحالية لبيئة الإنتاج الخاصة بالمشروع: deployed، building، failed، queued، أو no deployments. لا تحتاج إلى مصادقة، لذا تعرض لأي شخص يقرأ المستودع، وترتبط مرة أخرى بالمشروع في KPanel.

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

الحفاظ على صحته

ملف README يصف إعداداً لم يعد المشروع يحتويه أسوأ من عدم وجود README، لأن الناس يثقون به. عادتان تحافظان على دقته:

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

استكشاف الأخطاء

علامة التبويب تعرض إصدار قديم. ذاكرة التخزين المؤقت لمدة خمس دقائق. انتظر وأعد التحميل.

لم يتم العثور على README، لكن هناك واحد. تحقق من أنه في جذر المستودع وباسم README.md. على GitLab و Bitbucket يجب أن يتطابق الاسم تماماً.

المستودع متصل لكن علامة التبويب تقول إنه ليس كذلك. قد يكون الاتصال قد فقد الوصول، على سبيل المثال إذا تمت إزالة التكامل من جانب المزود. أعد توصيله من إعدادات المشروع.

الصور لا تُحمل. المسارات النسبية لا تتحل هنا. استخدم عناوين URL المطلقة.

الشارة تعرض عدم وجود عمليات نشر. بيئة الإنتاج لم تكن لديها قط نشر ناجح. انشر مرة واحدة وتتحدث.

الخطوات التالية

Orbit Deployment Pipeline، النسخة المباشرة مما يحاول ملف README عادة وصفه.
Orbit Project Settings للحصول على شارة الحالة وبقية التكوين.
Environment Variables in Orbit للقيم التي يجب على ملف README أن لا يحتويها أبداً.