تكامل GitLab
حوّل تسجيلات الشاشة إلى مستندات Markdown في GitLab
سجّل سير العمل مرة واحدة. تقوم Clevera بكتابة الدليل التوضيحي ورفعه (commit) إلى مشروع ومجلد GitLab الذي تختاره، كملف Markdown مع لقطات الشاشة الخاصة به، بحيث يلتقطه خط أنابيب توثيق كـ كود الخاص بك مثل أي تغيير آخر.
Markdown الخاص بـ GitLab
لقطات شاشة مرفوعة إلى المشروع
يعمل مع GitLab Pages وMkDocs
لا توجد أرصدة للنشر
ما يمكنك فعله
التوثيق كـ كود،
دون أن يضطر أحد لكتابته.
الفرق التي تعمل على GitLab تتعامل بالفعل مع التوثيق كأنه كود: فهو يعيش في مشروع، وله سجل تاريخي، ويقوم خط أنابيب بنشره. الجزء الصعب لم يكن أبداً خط الأنابيب، بل كان كتابة الأدلة. تقوم Clevera بكتابتها من تسجيل شاشة وتضعها في المجلد الذي يقرأ منه خط الأنابيب الخاص بك.
دليل من كل جولة تعريفية
اعرض الميزة مرة واحدة على الشاشة. تحوّل Clevera التسجيل إلى دليل مكتوب بخطوات مرقمة ولقطات شاشة، جاهز لدليل المشروع أو مستندات المنتج.
خط الأنابيب الخاص بك يتولى الباقي
كل عملية نشر هي commit عادي على الفرع الافتراضي، لذا يقوم GitLab Pages أو MkDocs أو Hugo بإعادة بناء الموقع تماماً كما يفعلون مع تغييرات أعضاء الفريق.
صور تعيش داخل المشروع
يتم رفع لقطات الشاشة بجانب ملف Markdown وربطها بمسار نسبي. هي لا تعتمد على Clevera، والمشروع الخاص يبقيها خاصة.
التحديثات كـ commits مقروءة
صحح المقالة في Clevera وانشرها مجدداً. يتم استبدال نفس الملف وصوره في commit بعنوان "تحديث المقالة"، لذا يظهر السجل ما تغير ومتى.
أي مشروع، أي مجلد
اختر من بين كل مشاريع GitLab حيث يكون الحساب المتصل مطوراً (Developer) أو أعلى، واكتب المجلد: docs, handbook/support أو جذر المشروع.
يلتزم بقواعد الفروع الخاصة بك
تحترم Clevera الفروع المحمية. إذا كان يُسمح فقط للمشرفين (Maintainers) بالدفع (push) إلى main، اتصل بحساب مشرف أو اسمح للمطورين بالدفع.
كيف يعمل
من التسجيل إلى مشروع GitLab
في أربع خطوات.
يقوم المالك أو المسؤول بربط GitLab مرة واحدة. بعد ذلك، يمكن لأي شخص لديه صلاحية تعديل مقالة نشرها من المحرر.
- 1
ربط GitLab.com
سجّل الدخول إلى GitLab وامنح الصلاحية لـ Clevera. ستظهر قائمة بالمشاريع التي يكون حسابك فيها مطوراً أو أعلى. - 2
Clevera تكتب الدليل
من تسجيل الشاشة، تكتب Clevera مقالة المساعدة: العناوين، الخطوات المرقمة، التنبيهات، ولقطات الشاشة. - 3
اختر المشروع والمجلد
في المشاركة (Share)، افتح النشر (Publish)، اختر مشروع GitLab والمجلد، واضغط على نشر إلى GitLab. - 4
يصل commit واحد
يصل ملف Markdown وصوره معاً في commit واحد على الفرع الافتراضي، ويعمل خط الأنابيب الخاص بك.
شاهد ذلك في Clevera
النشر إلى GitLab،
من نافذة مشاركة المقالة.
لا تصدير، لا نسخ لـ Markdown يدوياً، لا سحب لقطات الشاشة إلى المستودع. نافذة المشاركة التي تمنحك رابطاً وكود تضمين تقوم أيضاً بالرفع إلى GitLab.
اختر المشروع والمجلد
تُظهر القائمة المشاريع التي يكون حساب GitLab المتصل فيها مطوراً أو أعلى، مرتبة حسب الأحدث. اكتب المجلد الذي تعيش فيه مستنداتك، مثل docs/guides؛ المجلدات التي لا وجود لها بعد سيتم إنشاؤها في نفس الـ commit.
تتذكر Clevera المشروع والمجلد، لذا تذهب المقالة التالية إلى نفس المكان.
إعادة النشر دون ملفات مكررة
قبل الكتابة، تبحث Clevera عن ملف بنفس الاسم في ذلك المجلد. إذا وجدت واحداً، يمكنك الاختيار: استبداله في commit جديد، أو الاحتفاظ به ونشر هذه النسخة بعنوان جديد.
النشر يسير في اتجاه واحد فقط. أي تعديل يجريه شخص ما على الملف في GitLab لا يعود أبداً إلى مقالة Clevera.
GitLab بجانب بقية أدواتك
تحتفظ بعض الفرق بمستندات المنتج في GitLab والويكي الداخلي في مكان آخر. اربط كل أداة مرة واحدة وانشر نفس المقالة إلى GitLab، Confluence أو Notion من نفس علامة التبويب.
مملوءة لأجلك
ما يحتويه كل commit
وما تقرره أنت.
تكتب Clevera ملف Markdown يعرضه GitLab في واجهة الملفات الخاصة به، وتقوم مولدات المواقع الساكنة ببنائه بشكل نظيف. إليك بالضبط ما يضعه النشر في مشروعك.
- المشروع والمجلدأنت تختار
- أي مشروع على GitLab.com حيث يكون الحساب المتصل مطوراً أو أعلى، وأي مجلد فيه. يبدأ المجلد بـ
docs؛ اتركه فارغاً لجذر المشروع. - اسم الملفمحدد لأجلك
- عنوان المقالة بأحرف صغيرة مع واصلات، وينتهي بـ
.md. "Reset a customer password" تصبحreset-a-customer-password.md. العناوين التي تحتوي على علامات تشكيل أو غير اللاتينية تُكتب بأحرف لاتينية، وتُقص الأسماء عند 80 حرفاً. - Front matterمحدد لأجلك
- كتلة YAML تحتوي على
title,created_at,updated_atوsource. تقرأ MkDocs وHugo وDocusaurus العنوان وتتجاهل الباقي. - التنبيهات والتنسيقتم تحويلها لأجلك
- تتحول التنبيهات إلى تنبيهات GitLab مع عنوانها على نفس السطر، مثل
> [!WARNING] Careful. الجداول، قوائم المهام، المعادلات، الكود المنسق مع لغته، وأقسام<details>القابلة للطي تظهر كما يعرضها GitLab. - لقطات الشاشةمحدد لأجلك
- مرفوعة إلى
assets/<file name>/في نفس المجلد، في نفس الـ commit، مع كل تعليق توضيحي بخط مائل تحت صورته. - Commitمحدد لأجلك
- commit واحد على الفرع الافتراضي مع الرسالة
Add article: …أوUpdate article: …، من تأليف حساب GitLab الذي ربط Clevera. - الفيديوهاتمحدد لأجلك
- الفيديو الموضوع داخل المقالة يصبح صورة غلاف ترتبط بمشغل الفيديو، بالإضافة إلى رابط ▶ مع عنوانه. التسجيل الذي جاءت منه المقالة لا يُضاف.
الإعداد
إعداد تكامل GitLab
في حوالي دقيقتين.
تحتاج إلى مساحة عمل Clevera على خطة Pro أو Custom وحساب GitLab.com. يقوم مالك مساحة العمل أو المسؤول بربط GitLab؛ بعد ذلك، يمكن لأي شخص لديه صلاحية تعديل مقالة نشرها. النشر لا يستهلك أرصدة.
- 1
افتح التكاملات
في Clevera، افتح قائمة مساحة العمل، اختر Integrations، ابحث عن GitLab تحت Code repositories واضغط على Connect. - 2
امنح الصلاحية لـ Clevera على GitLab.com
يطلب GitLab نطاقات api, read_user, read_repository و write_repository ، التي تحتاجها واجهة برمجة تطبيقات الملفات الخاصة به لإنشاء وتحديث الملفات. اضغط على Authorize. - 3
تحقق من الدور
استخدم حساباً يكون مطوراً أو أعلى في كل مشروع. للرفع إلى فرع افتراضي محمي، يحتاج عادةً إلى Maintainer؛ حساب بوت مشترك يعمل بشكل جيد. - 4
انشر مقالة
في محرر المقالات، اضغط على Share، افتح Publish، اضغط على مربع GitLab، اختر المشروع والمجلد، واضغط على Publish to GitLab. - 5
افتحها في GitLab
عندما ترى "Published to GitLab."، اضغط على Open in GitLab لرؤية الملف والـ commit.
أسئلة تكامل GitLab
ليس اليوم. تتصل Clevera بـ GitLab.com فقط. خوادم GitLab المدارة ذاتياً غير مدعومة، لذا لا يمكن أن يكون مشروع على مثيل GitLab الخاص بك هدفاً للنشر.
لا. تقوم Clevera بالرفع مباشرة إلى الفرع الافتراضي للمشروع، عادةً main، ولا يمكنك اختيار فرع آخر. إذا كان فريقك يراجع المستندات في طلبات الدمج، راجع المقالة في Clevera قبل النشر، أو انشر إلى مشروع يُسمح فيه بالـ commits المباشرة.
غالباً بسبب فرع محمي. يحمي GitLab الفرع الافتراضي وعادةً ما يسمح للمشرفين فقط بالدفع إليه. امنح الحساب المتصل دور المشرف، أو اسمح للمطورين بالدفع تحت Settings → Repository → Protected branches.
نعم. وجه المجلد إلى المجلد الذي يبني منه موقعك. كل عملية نشر هي commit عادي، لذا يعمل خط أنابيب CI/CD الخاص بك كالمعتاد، ويقرأ المولد title من الـ front matter. تأكد من أن قالبك يعرض التنبيهات والأقسام القابلة للطي.
لا يتغير شيء في GitLab حتى تقوم بالنشر مرة أخرى. عندها تعثر Clevera على الملف الموجود وتتيح لك تحديثه في التزام (commit) جديد. إذا قمت بإعادة تسمية المقالة، يصبح العنوان الجديد ملفاً جديداً؛ احذف الملف القديم في GitLab بنفسك. لا تقوم Clevera أبداً بحذف الملفات من مشروعك.
تحتوي مساحة العمل على اتصال واحد بـ GitLab، ويؤدي الربط مرة أخرى إلى استبداله. استخدم حساباً عضواً في كل مشروع تنشر إليه.
يعد النشر إلى GitLab جزءاً من خطتي Pro و Custom، ولا يستهلك النشر أي رصيد. أما إنشاء المقالة نفسها فيستهلك الرصيد كالمعتاد. راجع الأسعار.
نعم. اربط كل أداة مرة واحدة وانشر نفس المقالة إلى أي عدد تريده منها. راجع GitHub و Bitbucket ، أو كل عمليات الربط.
دليلك القادم، موجود بالفعل في المشروع.
سجله مرة واحدة. تقوم Clevera بكتابة الدليل وإضافته (commit) إلى GitLab، مع لقطات الشاشة وكل شيء.