تثبيت وتهيئة Jigsaw في بيئة ServBay

نظرة عامة

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

ما هو Jigsaw؟

Jigsaw هو مولد مواقع ثابتة مبني على مكونات Laravel، طورته شركة Tighten. يستفيد من قوة ومرونة محرك قوالب Laravel Blade، ويستخدم ملفات Markdown لإنشاء مواقع HTML ثابتة بالكامل. يناسب Jigsaw بناء مواقع التوثيق، المدونات، صفحات الهبوط التسويقية، أو أي موقع لا يحتاج إلى قاعدة بيانات خلفية أو معالجة ديناميكية على الخادم. من أهم ميزاته:

• استخدام أدوات مألوفة: إذا كنت على دراية بـ Laravel أو قوالب Blade فسيكون تعلم Jigsaw سهلًا جدًا عليك.
• الأداء والأمان: المواقع الثابتة الناتجة سريعة للغاية وأكثر أمانًا نظرًا لعدم وجود كود ينفذ على الخادم.
• قوالب مرنة: يمكنك بناء تنسيقات وعناصر معقدة باستخدام Blade.
• دعم Markdown: كتابة المحتوى بكل سهولة.

حالات الاستخدام

Jigsaw مناسب للحالات التالية:

• مواقع توثيق المشاريع وواجهات برمجة التطبيقات (API)
• المدونات الشخصية أو مواقع مشاركة التقنية
• صفحات الهبوط التسويقية للشركات أو المنتجات
• مواقع العرض الصغيرة
• أي موقع ثابت يتطلب أداء عالي ودرجة أمان مرتفعة، ومحتواه غير متغير باستمرار

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

قبل البدء، يرجى التأكد من تحقيق الشروط التالية:

1. تثبيت ServBay وتشغيله: عليك تثبيت وبدء ServBay على نظام macOS. توفر ServBay جميع البرمجيات اللازمة مثل PHP وComposer وNode.js/npm لتثبيت وتشغيل Jigsaw.
2. معرفة أوامر الطرفية الأساسية: ستحتاج إلى تنفيذ بعض الأوامر عبر الطرفية.
3. فهم أساسي لـ Composer وnpm: يعتمد تثبيت Jigsaw على Composer، وتجميع الأصول الأمامية يحتاج npm.

خطوات التثبيت والتهيئة

في هذا القسم سنوضح بالتفصيل خطوات إعداد مشروع Jigsaw ضمن بيئة ServBay.

الخطوة 1: إنشاء دليل المشروع

أولاً، افتح تطبيق الطرفية وتوجه إلى دليل الجذر للمواقع المقترح من ServBay /Applications/ServBay/www، وأنشئ مجلدًا فرعيًا جديدًا لمشروع Jigsaw.

cd /Applications/ServBay/www
mkdir servbay-jigsaw-demo
cd servbay-jigsaw-demo

سمّينا دليل المشروع servbay-jigsaw-demo وسيتم حفظ جميع ملفات المشروع بداخله.

الخطوة 2: إنشاء مشروع Jigsaw باستخدام Composer

تم تثبيت Composer مسبقًا وإعداده في ServBay. يمكنك استخدام أمر composer مباشرة في أي نافذة طرفية. من داخل المجلد الذي أنشأته (/Applications/ServBay/www/servbay-jigsaw-demo)، نفّذ الأمر التالي لإنشاء مشروع Jigsaw:

composer create-project tightenco/jigsaw .

سيقوم هذا الأمر بتنزيل أحدث إصدار من Jigsaw وجميع الاعتمادات البرمجية الخاصة به إلى المجلد الحالي (.). لاحظ أن النقطة في نهاية الأمر تعني تثبيت المشروع في نفس المجلد، وليس في مجلد فرعي جديد باسم jigsaw.

الخطوة 3: تهيئة موقع ServBay

لتتمكن من تصفح موقع Jigsaw عبر المتصفح، يجب عليك إضافة الموقع محليًا من خلال لوحة ServBay.

1. افتح واجهة ServBay: انقر مزدوجًا على أيقونة ServBay أو من شريط القوائم.
2. انتقل إلى "المواقع": من القائمة الجانبية، اختر تبويب "المواقع".
3. أضف موقعًا جديدًا: انقر على زر "+" في الأسفل واختر "إضافة موقع".
4. املأ تفاصيل الموقع:
   • الاسم (Name): أدخل اسمًا تعرف به الموقع مثلًا ServBay Jigsaw Demo.
   • النطاق (Domain): أدخل النطاق الذي ترغب باستخدامه لزيارة الموقع محليًا. يفضل استخدام لاحقة .servbay.demo لتجنب تعارض مع النطاقات الحقيقية، مثلًا: jigsaw-demo.servbay.demo. سيضيف ServBay تلقائيًا دعم لهذه النطاقات.
   • نوع الموقع (Site Type): اختر PHP ، حيث يتطلب البناء بيئة PHP.
   • نسخة PHP (PHP Version): اختر نسخة PHP مثبتة بالفعل في ServBay (ويُفضل نسخة حديثة ومستقرة).
   • الجذر (Site Root): هذه الخطوة مهمة جدًا. الملفات الثابتة الناتجة عن بناء Jigsaw تحفظ افتراضيًا في مجلد build_local ضمن جذر المشروع. لذلك يجب تعيين الدليل الجذر إلى: /Applications/ServBay/www/servbay-jigsaw-demo/build_local
5. احفظ وطبق التغييرات: بعد إدخال جميع البيانات، انقر "حفظ". ستظهر مطالبة لتأكيد تطبيق التعديلات. بعد الموافقة سيقوم ServBay تلقائيًا بتحديث إعدادات الخادم (Caddy أو Nginx) وتفعيل HTTPS للموقع.

الخطوة 4: تثبيت الاعتمادات الأمامية

عادة ما يستخدم مشروع Jigsaw npm لإدارة وتجميع الأصول الأمامية (مثل SASS وملفات JavaScript). يتوفر Node.js وnpm مدمجين ضمن ServBay.

من مجلد المشروع (/Applications/ServBay/www/servbay-jigsaw-demo)، نفّذ الأمر التالي لتثبيت الاعتمادات الأمامية:

npm install

سيعمل الأمر على قراءة ملف package.json وتثبيت الحزم المطلوبة إلى مجلد node_modules.

الخطوة 5: بناء موقع Jigsaw

بعد تثبيت جميع الاعتمادات، يجب عليك الآن توليد الموقع الثابت عبر أمر البناء الخاص بـ Jigsaw.

من داخل مجلد المشروع، نفّذ الأمر التالي:

./vendor/bin/jigsaw build

يقوم هذا الأمر بـ:

1. معالجة ملفات Markdown وقوالب Blade داخل مجلد source.
2. تنفيذ مهام التجميع المعرفة في webpack.mix.js (إذا تم تضمين Laravel Mix عبر npm install).
3. إخراج ملفات HTML وCSS وJS وجميع الموارد الأخرى إلى المجلد build_local.

الخطوة 6: تصفح الموقع

الآن أصبحت جميع الملفات الثابتة لموقعك مخزنة ضمن /Applications/ServBay/www/servbay-jigsaw-demo/build_local. وبما أنك ضبطت الجذر إلى هذا المجلد عبر ServBay، فيمكنك الآن تصفح الموقع عبر النطاق المحلي الذي هيأته.

افتح المتصفح واتجه إلى النطاق الذي قمت بتحديده في الخطوة 3، مثلًا: https://jigsaw-demo.servbay.demo. سيقوم ServBay تلقائيًا بإدارة شهادات HTTPS المحلية (عبر ServBay User CA)، وستظهر لك صفحة الترحيب الافتراضية الخاصة بـ Jigsaw.

التخصيص والتطوير

بعد إتمام إعداد البيئة الأساسية، يمكنك البدء بتخصيص محتوى ومظهر موقعك المبني بJigsaw.

تحرير المحتوى والقوالب

• الشفرة المصدرية للموقع توجد في مجلد source ضمن الجذر.
• تنسيقات HTML والمكونات تستخدم قوالب Blade، وتوجد في مجلدات فرعية مثل source/_layouts وsource/_partials.
• غالبًا ما يُكتب المحتوى الرئيسي باستخدام Markdown ويُحفظ ضمن مجلد source أو مجلداته الفرعية (مثلًا: source/index.md، source/about.md).
• مقالات المدونة عادة توضع في source/_posts وفق تنسيق تسمية: YYYY-MM-DD-slug.md.

إضافة صفحة أو مقالة جديدة

لإضافة صفحة أو تدوينة جديدة، أنشئ ملف Markdown جديد في مجلد source أو المجلد المناسب (مثل source/_posts).

على سبيل المثال، أنشئ ملف source/about.md:

---
title: "من نحن"
description: "تعرف على المزيد حول ServBay Jigsaw Demo"
---

# من نحن

هذه صفحة "من نحن" تم بناؤها باستخدام Jigsaw.

يمكنك هنا إضافة نبذة عن الشركة أو معلومات حول الفريق وغير ذلك.

تخصيص الأنماط والبرمجيات الأمامية

عادة يتم تجميع الأصول الأمامية (CSS وJS) في Jigsaw باستخدام Laravel Mix (webpack.mix.js):

• ملفات الأنماط (غالبًا SASS/SCSS) في source/_assets/sass.
• ملفات الجافاسكربت في source/_assets/js.

يمكنك تجميع هذه الموارد من خلال تنفيذ أوامر npm من مجلد المشروع:

• npm run dev: لتجميع الأصول في وضع التطوير (مع source maps وبدون ضغط).
• npm run watch: لمتابعة أي تغييرات تلقائيًا وإعادة التجميع أثناء التطوير.
• npm run prod: لتجميع الأصول في وضع الإنتاج (يشمل ضغط وتحسين الملفات).

على سبيل المثال، بعد تعديل الملف source/_assets/sass/main.scss، نفّذ npm run dev أو npm run watch لإنشاء ملف CSS بشكل تلقائي.

إعادة بناء الموقع

ملاحظة هامة: عند أي تعديل في ملفات المحتوى (Markdown) أو ملفات القوالب (Blade) داخل مجلد source، يجب دائمًا إعادة بناء الموقع باستخدام أمر Jigsaw:

./vendor/bin/jigsaw build

أما عند تعديل ملفات الأصول الأمامية (SASS, JS)، فعليك تشغيل npm run dev أو npm run watch لإعادة التجميع. في أغلب مشاريع Jigsaw، يقوم أمر build أيضًا بتحفيز Mix لتجميع الأصول، لكن الفصل بين العمليتين أحيانًا يساعد في تتبع الأخطاء.

ملاحظات هامة

• دليل الإخراج: يقوم Jigsaw ببناء ملفات التطوير في build_local (لبيئة التطوير) وملفات الإنتاج في build_production. تأكد من ضبط "جذر الموقع" في ServBay على المجلد الذي ترغب بتصفحه (عادة التطوير: build_local).
• الخادم: يستخدم ServBay خادمي Caddy أو Nginx لتقديم الملفات الثابتة بكفاءة من build_local. لا حاجة لاستعمال أمر jigsaw serve المدمج (يُستخدم فقط للمعاينة السريعة، أما سيرفرات ServBay فهي أفضل للأعمال التطويرية).
• HTTPS: يقوم ServBay تلقائيًا بتهيئة HTTPS لنطاقات .servbay.demo عبر ServBay User CA. قد تحتاج إلى منح الثقة لهذه الشهادة من إعدادات النظام لتجنب تحذير المتصفح.
• بناء نظيف: إذا واجهت مشاكل غريبة أثناء البناء، جرب الأمر: ./vendor/bin/jigsaw build --clean لبناء نظيف من الصفر.

الأسئلة المتكررة (FAQ)

س: عدلت ملف Markdown، لكن لا أرى التغييرات في المتصفح؟

ج: عليك تنفيذ الأمر ./vendor/bin/jigsaw build بعد أي تعديل في المحتوى أو القوالب لإعادة توليد ملفات الموقع.

س: عدلت ملف SCSS، لكن الأنماط لم تتغير؟

ج: يجب عليك تشغيل npm run dev أو npm run watch بعد أي تعديل على الأصول الأمامية لإعادة التجميع.

س: يظهر لي “لا يمكن الوصول” أو “الملف غير موجود” عند زيارة النطاق؟

ج: تحقق من الأمور التالية:

1. تأكد من أن ServBay يعمل.
2. راجع إعدادات الموقع في ServBay: هل النطاق صحيح؟ هل الجذر يشير إلى /Applications/ServBay/www/servbay-jigsaw-demo/build_local؟
3. هل قمت ببناء الموقع فعليًا عبر ./vendor/bin/jigsaw build؟ وتأكد من وجود ملفات (مثل index.html) داخل مجلد build_local.

س: كيف أنشر موقع Jigsaw؟

ج: يخرج Jigsaw ملفات ثابتة فقط. عادةً:

1. شغّل ./vendor/bin/jigsaw build production لبناء ملفات الإنتاج المحسنة.
2. ارفع كل الملفات من مجلد build_production إلى خدمة استضافة مواقع ثابتة (مثل Netlify أو Vercel أو GitHub Pages أو أي مزود سحابي يدعم الملفات الثابتة).

الخلاصة

بفضل ServBay، أصبح تثبيت وتهيئة مولد المواقع الثابتة Jigsaw على نظام macOS عملية سريعة وسهلة للغاية. توفر ServBay كل الأدوات الضرورية (PHP, Composer, Node.js, npm) وسهولة تامة في إعداد خوادم الويب المحلية. باتباع هذا الدليل، يمكنك إطلاق مشروع Jigsaw بسرعة والاستفادة من إمكانيات ServBay لتحسين سير عملك التطويري المحلي.