في Look Scanned، نعمل باستمرار على تحسين بنيتنا التحتية لتوفير وثائق أفضل وممارسات تطوير أكثر أمانًا. اليوم، يسعدنا مشاركة تفاصيل حول ترقية كبيرة لموقع وثائق How-To الخاص بنا: الترحيل من تطبيق Vue + Vite مخصص إلى VitePress، مع تعزيز أمان CI/CD باستخدام npm Trusted Publishers في نفس الوقت.
📚 لماذا قمنا بالترحيل إلى VitePress
يعمل موقع وثائق How-To الخاص بنا (github.com/lookscanned/how-to) كدليل استخدام شامل لـ Look Scanned. بينما عمل إعداد Vue + Vite السابق بشكل جيد، أدركنا أن VitePress سيكون خيارًا أفضل لموقع وثائق يعتمد على المحتوى.
ما هو VitePress؟
VitePress هو مولد مواقع ثابتة مصمم خصيصًا للوثائق. مبني على Vite و Vue 3، يجمع بين أفضل ما في العالمين: تجربة تطوير سريعة للغاية مع ميزات وثائق قوية جاهزة للاستخدام.
الفوائد الرئيسية للترحيل
🎯 هندسة معمارية أفضل للوثائق
- التوجيه المبني على الملفات: يصبح كل ملف markdown صفحة تلقائيًا، مما يجعل تنظيم المحتوى بديهيًا
- ميزات وثائق مدمجة: جدول المحتويات، البحث، التدويل، والمزيد تأتي مكونة مسبقًا
- إنشاء موقع ثابت: يوفر HTML المعروض مسبقًا SEO ممتاز وتحميل فوري للصفحة
⚡ تحسين تجربة المطور
- إعادة تحميل فورية ساخنة: تظهر التغييرات على الفور أثناء التطوير
- Markdown أولاً: ركز على المحتوى، وليس على بناء المكونات
- دعم مكونات Vue: عند الحاجة، لا يزال بإمكاننا استخدام مكونات Vue مخصصة داخل markdown
🔧 صيانة أسهل
- بنية أوضح: تتبع الوثائق الاتفاقيات، مما يقلل الحمل المعرفي للمساهمين
- بناءات أكثر استقرارًا: تؤدي بنية VitePress ذات الرأي إلى بناءات أكثر قابلية للتكرار
- تعاون أفضل: يمكن لأعضاء الفريق المساهمة في الوثائق دون معرفة عميقة بـ Vue
🔒 تعزيز الأمان مع npm Trusted Publishers
إلى جانب ترحيل VitePress، قمنا بتنفيذ تحسين أمان حاسم: npm Trusted Publishers باستخدام مصادقة OIDC.
المشكلة مع رموز npm التقليدية
سابقًا، كان نشر الحزم إلى npm يتطلب تخزين NPM_TOKEN طويل الأمد في أسرار المستودع. لهذا النهج عدة عيوب:
- خطر أمني: يمكن كشف الرموز عن طريق الخطأ أو اختراقها
- عبء الإدارة: تحتاج الرموز إلى تدوير وتحديثات يدوية
- تحديات التدقيق: صعوبة تتبع من نشر ماذا ومتى
الحل: النشر الموثوق المبني على OIDC
يستفيد npm Trusted Publishers من OpenID Connect (OIDC) لتمكين النشر الآمن بدون رموز مباشرة من GitHub Actions. إليك كيف يعمل:
- لا توجد أسرار مخزنة: بدلاً من حفظ الرموز، تطلب GitHub Actions بيانات اعتماد قصيرة الأجل من npm
- التحقق من الهوية: يتحقق npm من أن طلب النشر جاء من مستودع GitHub المصرح به
- إدارة تلقائية لبيانات الاعتماد: يتم إصدار بيانات الاعتماد تلقائيًا وتنتهي صلاحيتها بسرعة
الفوائد في العالم الحقيقي
يجلب هذا التغيير تحسينات فورية لسير عمل التطوير لدينا:
- ✅ لا مزيد من إدارة الرموز: لا حاجة لإنشاء أو تخزين أو تدوير رموز npm
- ✅ تقليل سطح الهجوم: تقلل بيانات الاعتماد قصيرة الأجل من خطر التعرض
- ✅ قابلية تدقيق أفضل: يرتبط كل إجراء نشر بتشغيل GitHub Actions محدد
- ✅ أفضل الممارسات الحديثة: يتماشى مع مبادئ أمان الثقة المعدومة
ملاحظة فنية: لدعم npm Trusted Publishers، قمنا بتحديث تكوين CI لاستخدام Node.js lts/*، مما يضمن حصولنا على أحدث إصدار npm المطلوب لمصادقة OIDC.
📦 الجدول الزمني للإصدار
تم إكمال الترحيل من خلال ثلاثة إصدارات في 19 ديسمبر 2025:
- v2.0.0: الترحيل الأساسي من Vue + Vite إلى VitePress (تغيير جذري)
- v2.0.1: إصلاح CI لدعم npm Trusted Publishers مع إصدار Node.js المناسب
- v2.0.2: تحسين الأداء من خلال نقل
@fontsource/noto-monoإلى devDependencies
🌍 استمرار الدعم متعدد اللغات
ملاحظة مهمة: تولد وثائق How-To الخاصة بنا ملفات PDF متعددة اللغات التي تم استخدامها دائمًا كملفات أمثلة في تطبيق Look Scanned الرئيسي (متاح على lookscanned.io/en/scan). لا يغير ترحيل VitePress هذا هذه الوظيفة - فهو يوفر فقط أساسًا أفضل للحفاظ على البنية التحتية للوثائق لدينا وتحسينها.
💡 ما يعنيه هذا للمستخدمين
إذا كنت تستخدم وثائق Look Scanned:
- نفس الوصول، تجربة أفضل: تبقى الوثائق في نفس عنوان URL مع تحسين التحميل والتنقل
- أكثر موثوقية: يعني إنشاء الموقع الثابت تحميلات أسرع واستقرار أفضل
- بحث واكتشاف أفضل: يساعدك البحث المدمج في VitePress في العثور على إجابات أسرع
- استمرار دعم PDF: يستمر إنشاء PDF متعدد اللغات كما كان من قبل
🚀 ما التالي
مع اكتمال ترقية البنية التحتية، نركز على تحسينات المحتوى:
- حالات استخدام موسعة: المزيد من الأمثلة العملية والأدلة خطوة بخطوة
- تحسينات الاتساق: تحسين المصطلحات متعددة اللغات من أجل الوضوح
- تصدير PDF محسّن: تحسين تجربة إنشاء PDF عبر المتصفحات
جرب Look Scanned اليوم
يوفر Look Scanned تأثيرات مسح PDF قائمة على المتصفح وتعطي الأولوية للخصوصية دون تحميل ملفاتك في أي مكان. تجعل الوثائق المحسّنة البدء أسهل من أي وقت مضى.
👉 قم بزيارة lookscanned.io لتجربة مسح المستندات السريع والآمن في متصفحك.