إنشاء وتشغيل مشروع 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 سواء خلال التطوير أو الإنتاج وعرض الملفات الثابتة.
المتطلبات الأساسية
قبل البدء، تأكد من إنجاز الخطوات التالية:
- تثبيت ServBay: تأكد من تثبيت ServBay بنجاح على جهازك. إذا لم تقم بذلك بعد، راجع دليل تثبيت ServBay.
- تثبيت حزمة Node.js: عبر ServBay، تأكد من تثبيت وتفعيل الإصدار المطلوب من Node.js. يمكنك ذلك من لوحة تحكم ServBay في صفحة "الحزم". راجع استخدام Node.js.
إنشاء مشروع VitePress
تهيئة مجلد المشروع
أولًا، افتح تطبيق الطرفية لديك. يُنصح بإنشاء مجلد المشروع ضمن المجلد الجذري الافتراضي لمواقع ServBay، لتسهيل الإعداد لاحقًا.
macOS:
bashcd /Applications/ServBay/www mkdir servbay-vitepress-app cd servbay-vitepress-app
1
2
3Windows:
cmdcd C:\ServBay\www mkdir servbay-vitepress-app cd servbay-vitepress-app
1
2
3تثبيت VitePress وبدء التهيئة
داخل مجلد المشروع
servbay-vitepress-app
، استخدم npm أو yarn لتثبيت VitePress كاعتماد تطوير، ثم نفذ أمر التهيئة.bashnpm add -D vitepress npx vitepress init
1
2أو باستخدام Yarn:
bashyarn add -D vitepress yarn vitepress init
1
2سيقودك أمر التهيئة خلال بعض الإعدادات الأساسية كعنوان الموقع والوصف وغير ذلك. اتبع الإرشادات وأدخل المعلومات المناسبة:
┌ مرحبًا بك في 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
تعديل محتوى الصفحة الرئيسية
الملف الافتراضي للصفحة الرئيسية في VitePress يوجد ضمن
docs/index.md
. يمكنك فتحه بأي محرر نصوص وتعديل محتواه مثل:markdown# مرحبًا ServBay! نُرحب بك لاستخدام ServBay لتشغيل موقع VitePress الخاص بك. هذا موقع تجريبي محلي منشأ باستخدام VitePress، ويتم تقديمه عبر ServBay.
1
2
3
4
5
الدخول لوضع التطوير
خلال تطوير موقع VitePress غالبًا ستستخدم خادم التطوير المدمج والذي يوفر التحديث الفوري (hot reload) لمعاينة التعديلات مباشرة. سنستخدم هنا خاصية الوكيل العكسي في ServBay لتصفح موقعك عبر نطاق مخصص والاستفادة من تشفير SSL.
تشغيل خادم VitePress للتطوير
في الطرفية، تأكد أنك داخل مجلد المشروع (macOS:
/Applications/ServBay/www/servbay-vitepress-app
، Windows:C:\ServBay\www\servbay-vitepress-app
). لتشغيل خادم التطوير على منفذ معين (مثل 8585) نفذ:bashnpm run docs:dev -- --port 8585
1أو عبر Yarn:
bashyarn docs:dev --port 8585
1سيبدأ الخادم المحلي على المنفذ المحدد وسيتم عرض الرابط المحلي عادةً على شكل
http://localhost:8585
.إعداد موقع 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
.- الاسم: أدخل اسمًا تعريفيًا مثل
زيارة موقع التطوير
الآن يمكنك فتح المتصفح والدخول إلى
https://vitepress-dev.servbay.demo
لرؤية محتوى خادم VitePress الخاص بك. ومن خلال إعدادات ServBay حصلت تلقائيًا على شهادة SSL موقعة من ServBay User CA لتصفح مؤمن عبر HTTPS.
بناء نسخة الإنتاج
عند اكتمال توثيق VitePress وتصبح مستعدًا للنشر، عليك بناء نسخة ثابتة محسنة للموقع.
بناء نسخة الإنتاج
في الطرفية، ومن داخل مجلد المشروع (macOS:
/Applications/ServBay/www/servbay-vitepress-app
، Windows:C:\ServBay\www\servbay-vitepress-app
) شغِّل:bashnpm run docs:build
1أو عبر Yarn:
bashyarn docs:build
1سيقوم الأمر بتحويل ملفات Markdown والمكونات إلى مجموعة ملفات HTML وCSS وJavaScript ثابتة ومحسنة، وستكون الملفات الناتجة ضمن مجلد
docs/.vitepress/dist
.إعداد موقع 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
- macOS:
بعد الحفظ وتطبيق التغييرات، سيقوم ServBay بتكوين خادم الويب لتقديم الملفات مباشرة من المجلد المحدد.
- الاسم: أدخل اسمًا توضيحيًا مثل
زيارة موقع الإنتاج
الآن يمكنك فتح المتصفح والدخول إلى
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).
تفعيل
cleanUrls
في إعدادات VitePressحرر ملف إعدادات VitePress (
docs/.vitepress/config.mts
أوdocs/.vitepress/config.ts
) وأضف أو عدل خيارcleanUrls
:typescript// docs/.vitepress/config.mts import { defineConfig } from 'vitepress' export default defineConfig({ // ... إعدادات أخرى cleanUrls: true, // تفعيل الروابط النظيفة // ... إعدادات أخرى })
1
2
3
4
5
6
7
8أعد تشغيل أمر البناء باستخدام
npm run docs:build
.تكوين موقع 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
- macOS:
bash# استبدل بالنطاق الفعلي مثل 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 }
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25احفظ وطبق التغييرات.
زيارة موقعك بروابط نظيفة
يمكنك الآن الوصول إلى النطاق المخصص (مثل
https://vitepress-cleanurl.servbay.demo
) واستخدام الروابط بدون امتداد.html
، مثل زيارة صفحةabout
عبر الرابطhttps://vitepress-cleanurl.servbay.demo/about
.
ملخص
من خلال هذا الدليل تعلمت كيفية إنشاء وتطوير ونشر موقع توثيق باستخدام VitePress في بيئة ServBay. يقوم ServBay بتسهيل إدارة بيئة Node.js وكذلك إعداد خادم الويب المحلي، سواء أثناء التطوير مع الوكيل العكسي أو التشغيل النهائي بخدمة الملفات الثابتة، إلى جانب دعم تلقائي للنطاقات المخصصة وشهادات SSL.
باستخدام ServBay مع VitePress تستطيع بناء وحفظ مواقع توثيق تقنية عالية الجودة بكفاءة وسهولة.