إنشاء وتشغيل مشروع VitePress باستخدام ServBay

VitePress هو مُوَلِّد مواقع ثابتة حديث يعتمد على Vue، صُمم خصيصًا لبناء مواقع توثيق سريعة وجميلة وسهلة الصيانة. يعتمد في بنائه على Vite، ويوفر تجربة تطوير ممتازة وأداء عالي عند البناء. إذا كنت مطورًا بحاجة لإنشاء توثيق احترافي لمشروعك أو مكتبتك أو منتجك، فإن VitePress يعد خيارًا مثاليًا.

عند تطوير واختبار موقع VitePress محليًا، تصبح الحاجة لبيئة تطوير ويب محلية مستقرة وسهلة الإعداد أمرًا أساسيًا. وهنا يأتي دور ServBay، حيث يوفر العديد من إصدارات Node.js مع خوادم ويب قوية مثل Caddy أو Nginx، ما يجعل خدمة مشروع VitePress الخاص بك سهلة للغاية.

ستُرشدك هذه المقالة إلى كيفية الاستفادة من بيئة ServBay المدمجة، لإنشاء وتكوين وتشغيل مشروع VitePress من البداية، بما في ذلك إعداد الوكيل العكسي لخادم التطوير وخدمة الملفات الثابتة عند التكامل النهائي.

ما هو VitePress؟

VitePress هو مُوَلِّد مواقع ثابتة (SSG) مبني على Vite ويستفيد من قوة Vue 3 وسرعة Vite لإنشاء مواقع ثابتة، مع تفوق خاص في بناء مواقع التوثيق التقنية.

أهم ميزات VitePress وفوائده

• تجربة تطوير فائقة السرعة: بفضل ميزة الاستبدال السريع للوحدات (HMR) الخاصة بـ Vite، ستلاحظ تحديثات فورية على المتصفح مع أي تعديل، مما يزيد الإنتاجية.
• مدعوم بـ Vue: يمكنك إدراج مكونات Vue مباشرةً في ملفات Markdown، مما يمنح التوثيق تفاعلية وغنى أكبر.
• سهل الاستخدام: إعداد بسيط وجاهز للعمل فورًا، يركز على إنشاء المحتوى.
• أداء عالي: الملفات الناتجة صغيرة الحجم وسريعة التحميل، مع تجربة سلسة لتطبيق صفحة واحدة بفضل توجيه العميل المدمج.
• صديق لمحركات البحث (SEO): هيكلة HTML الناتجة تساعد محركات البحث في فهرسة الموقع بسهولة، مع دعم تخصيص وسوم الرأس.
• تعزيز Markdown: يدعم جميع مزايا CommonMark و GitHub Flavored Markdown (GFM) ويضيف المزيد من التركيبات البرمجية المحسنة.

تُمكنك VitePress من إنشاء مواقع توثيق عالية الجودة وقوية الأداء بسهولة.

إنشاء وتشغيل مشروع VitePress باستخدام ServBay

ServBay يسهل إدارة إصدارات Node.js وإعداد خادم ويب لخدمة مشروع VitePress سواء خلال التطوير أو الإنتاج وعرض الملفات الثابتة.

المتطلبات الأساسية

قبل البدء، تأكد من إنجاز الخطوات التالية:

1. تثبيت ServBay: تأكد من تثبيت ServBay بنجاح على جهازك. إذا لم تقم بذلك بعد، راجع دليل تثبيت ServBay.
2. تثبيت حزمة Node.js: عبر ServBay، تأكد من تثبيت وتفعيل الإصدار المطلوب من Node.js. يمكنك ذلك من لوحة تحكم ServBay في صفحة "الحزم". راجع استخدام Node.js.

إنشاء مشروع VitePress

1. تهيئة مجلد المشروع

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

   macOS:

   cd /Applications/ServBay/www
   mkdir servbay-vitepress-app
   cd servbay-vitepress-app

   Windows:

   cd C:\ServBay\www
   mkdir servbay-vitepress-app
   cd servbay-vitepress-app

2. تثبيت VitePress وبدء التهيئة

   داخل مجلد المشروع servbay-vitepress-app، استخدم npm أو yarn لتثبيت VitePress كاعتماد تطوير، ثم نفذ أمر التهيئة.

   npm add -D vitepress
   npx vitepress init

   أو باستخدام Yarn:

   yarn add -D vitepress
   yarn vitepress init

   سيقودك أمر التهيئة خلال بعض الإعدادات الأساسية كعنوان الموقع والوصف وغير ذلك. اتبع الإرشادات وأدخل المعلومات المناسبة:

    ┌  مرحبًا بك في VitePress!
    │
    ◇  أين يجب تهيئة إعدادات VitePress؟
    │  ./docs  # مجلد التوثيق الافتراضي؛ اضغط Enter للتأكيد
    │
    ◇  عنوان الموقع:
    │  ServBay VitePress Demo # أدخل عنوان موقعك، مثل ServBay VitePress Demo
    │
    ◇  وصف الموقع:
    │  موقع VitePress يعمل على ServBay # أدخل وصفًا لموقعك
    │
    ◇  السمة:
    │  السمة الافتراضية # اختر السمة؛ الاستخدام الافتراضي مناسب
    │
    ◇  هل تريد استخدام TypeScript لإعدادات التهيئة والسمات؟
    │  نعم # اختر حسب رغبتك
    │
    ◇  هل تضيف سكريبتات VitePress إلى package.json؟
    │  نعم # يُنصح باختيار نعم
    │
    └  تم! الآن شغل npm run docs:dev وابدأ بالكتابة.

   بعد الانتهاء، ستنشئ VitePress مجلدًا فرعيًا باسم docs داخل servbay-vitepress-app ويُولد ملفات الإعداد الافتراضية (.vitepress) وصفحات نموذجية (index.md، guide/index.md إلخ)، كما تُحدث ملف package.json بحيث يحتوي على سكريبتات مثل docs:dev وdocs:build.

تعديل محتوى مشروع VitePress

1. تعديل محتوى الصفحة الرئيسية

   الملف الافتراضي للصفحة الرئيسية في VitePress يوجد ضمن docs/index.md. يمكنك فتحه بأي محرر نصوص وتعديل محتواه مثل:

   # مرحبًا ServBay!
   
   نُرحب بك لاستخدام ServBay لتشغيل موقع VitePress الخاص بك.
   
   هذا موقع تجريبي محلي منشأ باستخدام VitePress، ويتم تقديمه عبر ServBay.

الدخول لوضع التطوير

خلال تطوير موقع VitePress غالبًا ستستخدم خادم التطوير المدمج والذي يوفر التحديث الفوري (hot reload) لمعاينة التعديلات مباشرة. سنستخدم هنا خاصية الوكيل العكسي في ServBay لتصفح موقعك عبر نطاق مخصص والاستفادة من تشفير SSL.

1. تشغيل خادم VitePress للتطوير

   في الطرفية، تأكد أنك داخل مجلد المشروع (macOS: /Applications/ServBay/www/servbay-vitepress-app، Windows: C:\ServBay\www\servbay-vitepress-app). لتشغيل خادم التطوير على منفذ معين (مثل 8585) نفذ:

   npm run docs:dev -- --port 8585

   أو عبر Yarn:

   yarn docs:dev --port 8585

   سيبدأ الخادم المحلي على المنفذ المحدد وسيتم عرض الرابط المحلي عادةً على شكل http://localhost:8585.

2. إعداد موقع ServBay (وكيل عكسي)

   افتح لوحة تحكم ServBay وانتقل إلى صفحة "المواقع" وأضف إعداد موقع جديد:

   • الاسم: أدخل اسمًا تعريفيًا مثل موقع VitePress للتطوير.
   • النطاق: أدخل النطاق المحلي المرغوب مثل vitepress-dev.servbay.demo (يُوصى بالاستخدام مع لاحقة .servbay.demo للعلامة التجارية وتجنب التعارضات).
   • نوع الموقع: اختر وكيل عكسي.
   • IP: أدخل 127.0.0.1 (المضيف المحلي).
   • المنفذ: أدخل المنفذ الذي استعملته، مثل 8585.

   بعد الحفظ وتطبيق التغييرات سيُعد ServBay خادم الويب (Caddy أو Nginx) ليُوجه الطلبات لـ https://vitepress-dev.servbay.demo إلى http://127.0.0.1:8585.

3. زيارة موقع التطوير

   الآن يمكنك فتح المتصفح والدخول إلى https://vitepress-dev.servbay.demo لرؤية محتوى خادم VitePress الخاص بك. ومن خلال إعدادات ServBay حصلت تلقائيًا على شهادة SSL موقعة من ServBay User CA لتصفح مؤمن عبر HTTPS.

بناء نسخة الإنتاج

عند اكتمال توثيق VitePress وتصبح مستعدًا للنشر، عليك بناء نسخة ثابتة محسنة للموقع.

1. بناء نسخة الإنتاج

   في الطرفية، ومن داخل مجلد المشروع (macOS: /Applications/ServBay/www/servbay-vitepress-app، Windows: C:\ServBay\www\servbay-vitepress-app) شغِّل:

   npm run docs:build

   أو عبر Yarn:

   yarn docs:build

   سيقوم الأمر بتحويل ملفات Markdown والمكونات إلى مجموعة ملفات HTML وCSS وJavaScript ثابتة ومحسنة، وستكون الملفات الناتجة ضمن مجلد docs/.vitepress/dist.

2. إعداد موقع ServBay (خدمة ملفات ثابتة)

   لأن النسخة النهائية هي ملفات ثابتة، يمكنك استخدام خاصية خدمة الملفات الثابتة في ServBay لتقديم الموقع مباشرة.

   افتح لوحة تحكم ServBay وأضف إعداد موقع جديد:

   • الاسم: أدخل اسمًا توضيحيًا مثل موقع VitePress للإنتاج.
   • النطاق: أدخل النطاق المطلوب مثل vitepress-prod.servbay.demo.
   • نوع الموقع: اختر ثابت.
   • المجلد الجذري للموقع: أدخل المسار المطلق للمجلد الذي يحوي ملفات الموقع:
     • macOS: /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
     • Windows: C:\ServBay\www\servbay-vitepress-app\docs\.vitepress\dist

   بعد الحفظ وتطبيق التغييرات، سيقوم ServBay بتكوين خادم الويب لتقديم الملفات مباشرة من المجلد المحدد.

3. زيارة موقع الإنتاج

   الآن يمكنك فتح المتصفح والدخول إلى https://vitepress-prod.servbay.demo لمعاينة موقع VitePress النهائي، وبنفس الوقت تحصل على النطاق المخصص وتشفير SSL تلقائيًا.

تشغيل الوضع ذو الروابط النظيفة (cleanUrls: true)

يدعم VitePress إعداد cleanUrls: true، مما يجعل روابط الصفحات خالية من الامتداد .html (مثل /guide/ بدلًا من /guide/index.html أو /about بدلًا من /about.html). يتطلب الأمر تكوين إضافي لخوادم الويب لضمان عمل تلك الروابط بنجاح.

يستخدم ServBay خوادم Caddy أو Nginx. فيما يلي مثال لتكوين Caddy باستخدام أمر try_files لمحاولة الوصول للملفات المناسبة (مع أو بدون الامتداد أو ملفات index).

1. تفعيل cleanUrls في إعدادات VitePress

   حرر ملف إعدادات VitePress (docs/.vitepress/config.mts أو docs/.vitepress/config.ts) وأضف أو عدل خيار cleanUrls:

   // docs/.vitepress/config.mts
   import { defineConfig } from 'vitepress'
   
   export default defineConfig({
     // ... إعدادات أخرى
     cleanUrls: true, // تفعيل الروابط النظيفة
     // ... إعدادات أخرى
   })

   أعد تشغيل أمر البناء باستخدام npm run docs:build.

2. تكوين موقع ServBay (إعداد Caddy مخصص)

   افتح لوحة تحكم ServBay وانتقل إلى موقع الإنتاج الخاص بـ VitePress (مثال: vitepress-prod.servbay.demo).

   • اضغط على زر التعديل.
   • فعل خيار إعداد مخصص.
   • ضمن منطقة إعدادات Caddy، أدخل الإعداد التالي (استبدل servbay-vitepress-test.prod بنطاقك الفعلي وعدل المسار لمجلد الموقع حسب نظامك):
     • macOS: /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
     • Windows: C:\ServBay\www\servbay-vitepress-app\docs\.vitepress\dist

   # استبدل بالنطاق الفعلي مثل vitepress-cleanurl.servbay.demo
   vitepress-cleanurl.servbay.demo {
       # تفعيل ضغط Brotli (zstd) و Gzip لتحسين السرعة
       encode zstd gzip
   
       # استيراد إعدادات السجل الافتراضي في ServBay للتشخيص
       import set-log vitepress-cleanurl.servbay.demo
   
       # إدارة شهادة SSL الداخلية تلقائيًا من ServBay
       tls internal
   
       # إعداد رئيسي: محاولة ايجاد الملف المناسب
       # 1. محاولة مطابقة المسار مباشرة (/about -> /about)
       # 2. محاولة البحث عن index.html ضمن المجلد (/guide/ -> /guide/index.html)
       # 3. محاولة إضافة .html للمسار (/about -> /about.html)
       try_files {path} {path}/index.html {path}.html
   
       # تعيين المجلد الجذري
       # macOS: root * /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
       # Windows: root * C:\ServBay\www\servbay-vitepress-app\docs\.vitepress\dist
       root * /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
   
       # تفعيل خدمة الملفات الثابتة
       file_server
   }

   احفظ وطبق التغييرات.

3. زيارة موقعك بروابط نظيفة

   يمكنك الآن الوصول إلى النطاق المخصص (مثل https://vitepress-cleanurl.servbay.demo) واستخدام الروابط بدون امتداد .html، مثل زيارة صفحة about عبر الرابط https://vitepress-cleanurl.servbay.demo/about.

ملخص

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

باستخدام ServBay مع VitePress تستطيع بناء وحفظ مواقع توثيق تقنية عالية الجودة بكفاءة وسهولة.