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

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

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

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

ما هو VitePress؟

VitePress هو مولد مواقع ثابتة (SSG) مبني على Vite، يستفيد من قدرات Vue 3 وأداء Vite السريع لإنشاء مواقع ثابتة، مع تركيز خاص على بناء وثائق تقنية متطورة.

الميزات والفوائد الرئيسية لـ VitePress

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

بفضل VitePress، يمكن للمطورين بناء مواقع توثيق عالية الجودة والأداء بسهولة.

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

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

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

قبل البدء، تأكد من استيفاء المتطلبات التالية:

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

إنشاء مشروع VitePress

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

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

   cd /Applications/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

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

    ┌  Welcome to VitePress!
    │
    ◇  Where should VitePress initialize the config?
    │  ./docs  # مجلد التوثيق الافتراضي، اضغط Enter للتأكيد
    │
    ◇  Site title:
    │  ServBay VitePress Demo # أدخل عنوان موقعك مثل ServBay VitePress Demo
    │
    ◇  Site description:
    │  A VitePress site running on ServBay # أدخل وصفاً مناسباً
    │
    ◇  Theme:
    │  Default Theme # اختر الثيم الافتراضي
    │
    ◇  Use TypeScript for config and theme files?
    │  Yes # استخدم TypeScript للإعدادات حسب تفضيلاتك
    │
    ◇  Add VitePress npm scripts to package.json?
    │  Yes # أضف السكريبتات إلى package.json، يُوصى باختيار Yes
    │
    └  Done! Now run npm run docs:dev and start writing.

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

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

1. تحرير الصفحة الرئيسية

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

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

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

عند تطوير موقعك باستخدام VitePress، يُستحسن استخدام خادم التطوير المدمج لأنه يوفر خاصية التحديث الفوري للصفحة عند حفظ أي تعديل. تستطيع عبر ServBay استخدام ميزة البروكسي العكسي وزيارة الموقع من نطاق مخصص مع دعم SSL.

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

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

   npm run docs:dev -- --port 8585

   أو عبر Yarn:

   yarn docs:dev --port 8585

   الآن سيعمل الخادم محلياً على المنفذ 8585 وستظهر رسالة بالعنوان المحلي عادة http://localhost:8585.

2. ضبط موقع ServBay (البروكسي العكسي)

   اذهب إلى لوحة تحكم ServBay، وادخل على صفحة "المواقع". اضغط على إضافة إعداد جديد لموقع.

   • الاسم: اسم مميز مثل موقع تطوير VitePress.
   • النطاق: اختر نطاقاً محلياً للموقع، ولتجنب التعارض واتباع معيار ServBay يفضل استخدام اللاحقة .servbay.demo مثل vitepress-dev.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 في متصفحك وستشاهد محتوى موقعك، مع الاستفادة من نطاق مخصص ودعم SSL الذي يولده ServBay بشكل تلقائي.

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

بمجرد الانتهاء من تطوير وثائقك باستخدام VitePress، يمكنك بناء نسخة إنتاجية مُحسَّنة.

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

   من الطرفية وفي مجلد servbay-vitepress-app، نفّذ:

   npm run docs:build

   أو:

   yarn docs:build

   ستجد الملفات الثابتة الناتجة (HTML، CSS، JS) ضمن docs/.vitepress/dist.

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

   النسخة الإنتاجية من VitePress هي مجرد ملفات ثابتة. يمكنك الآن ضبط موقع جديد بخدمة الملفات الثابتة عبر ServBay.

   من لوحة التحكم، اضف موقعاً جديداً:

   • الاسم: مثلاً موقع إنتاج VitePress.
   • النطاق: كـ vitepress-prod.servbay.demo.
   • نوع الموقع: اختر ثابت.
   • الجذر: ضع المسار المطلق إلى مجلد الملفات الناتج /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist.

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

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

   للوصول لموقعك، استخدم https://vitepress-prod.servbay.demo وستجد نسخة الإنتاج مع نطاق وSSL جاهزين.

العمل بوضع روابط التنقل النظيفة (cleanUrls: true)

يدعم VitePress خيار cleanUrls: true، حيث تظهر الروابط بدون اللاحقة .html مثل /guide/ بدلاً من /guide/index.html، أو /about بدلاً من /about.html. يلزم إعداد إضافي في خادم الويب حتى تعمل الروابط بهذا الشكل.

يستخدم ServBay Caddy أو Nginx كخادم ويب. فيما يلي مثال لضبط إعدادات Caddy باستخدام توجيه try_files لمحاكاة هذه السلوكيات:

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-prod.servbay.demo).

   • اضغط تعديل.
   • فعِّل خيار إعدادات مخصصة.
   • وأضف التكوين التالي (استبدل اسم النطاق والمسار حسب موقعك):

   # استبدل باسم نطاقك فعلياً (مثال: 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. الملف كما هو
       # 2. داخل المجلد index.html
       # 3. الملف بلاحقة .html
       try_files {path} {path}/index.html {path}.html
   
       # تحديد مجلد الموقع
       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، يمكنك بناء وصيانة مواقع توثيق تقنية عالية الجودة بكفاءة وسرعة.