نشر موقع HTML وCSS وJavaScript على GitHub Pages خطوة بخطوة
دليل عملي لنشر موقع ثابت على GitHub Pages، تنظيم الملفات، ضبط المسارات، إضافة sitemap وrobots وتحسين قابلية الفهرسة.
ابدأ بفهم Git قبل النشر
إذا كنت لا تزال في بداية استخدام Git وGitHub، فاطّلع أولًا على دليل Git وGitHub للمبتدئين لفهم المستودع والـcommit والـbranch ورفع التغييرات. هذا المقال يركز هنا على خطوة النشر والاستضافة بعد تجهيز المشروع.
هيكل مشروع مناسب
اجعل index.html نقطة الدخول الرئيسية، وضع المقالات في articles والصفحات الثابتة في pages والموارد مثل الصور وملفات CSS وJavaScript في assets. يسهل هذا التقسيم العثور على الملفات وصيانة المشروع لاحقًا.
المسارات النسبية
اختبر المسارات من الصفحة الرئيسية ومن صفحات المقالات أيضًا. فعلى سبيل المثال، تحتاج صفحة داخل articles عادةً إلى ../assets للوصول إلى الملفات المشتركة الموجودة في مجلد assets.
GitHub Pages
بعد رفع ملفات المشروع إلى المستودع، افتح إعدادات Pages وحدد مصدر النشر المناسب. وعندما يصبح الموقع متاحًا، افتح عنوان HTTPS النهائي وتأكد من أن الصفحات والموارد تُحمّل كما ينبغي.
SEO الفني
جهّز لكل مقال عنوانًا ووصفًا للبحث ورابط canonical وبيانات Open Graph وبيانات منظمة دقيقة. أنشئ كذلك sitemap.xml وrobots.txt، وتأكد من أن جميع هذه الإشارات تطابق المحتوى المنشور فعلًا.
الصور والسرعة
اختر أبعاد الصور بما يناسب موضع عرضها، وفعّل lazy loading للصور التي لا تظهر فور فتح الصفحة، وتخلّص من الملفات غير المستخدمة. ثم قِس الأداء بأدوات الاختبار بدل الاعتماد على تقديرات غير مؤكدة.
الخلاصة
يمكن للموقع الثابت أن يقدّم أداءً جيدًا ويسهل فهرسته عندما تكون بنية HTML منظمة، والمسارات سليمة، ويحتوي كل صفحة على محتوى مفيد.
مصادر وروابط موثوقة
قائمة تحقق بعد النشر
- افتح الصفحة الرئيسية وصفحة داخلية مباشرة عبر HTTPS.
- افحص الصور وCSS وJavaScript وتأكد من عدم وجود أخطاء 404.
- تحقق من أن canonical يشير إلى النطاق المعتمد، وأن sitemap يحتوي روابط عامة صحيحة.
- اختبر القائمة والروابط ونموذج الاتصال على الهاتف.
- افتح الموقع في نافذة خاصة للتأكد من أن النتيجة ليست نسخة مخزنة مؤقتًا.
تجنّب أخطاء المسارات
في GitHub Pages لمشروع داخل مسار مثل /project/ قد يشير المسار المطلق /assets/ إلى جذر النطاق بدل مجلد المشروع. اختبر الروابط من الصفحة الرئيسية ومن مجلد المقالات. راجع وثائق GitHub Pages الرسمية لإعدادات المصدر والنشر.
قائمة تحقق للنشر على GitHub Pages
تحقق من مصدر النشر والفرع والمجلد المحدد في إعدادات المستودع، ثم راجع سجل النشر إذا لم يظهر التحديث. في المواقع الثابتة، أكثر الأخطاء شيوعًا هي المسارات المطلقة غير المناسبة، وحالة الأحرف في أسماء الملفات، والروابط التي تعمل محليًا فقط.
- اختبر صفحة البداية وصفحات المقالات مباشرة بعد النشر.
- افحص الصور وCSS وJavaScript في أدوات المطور بحثًا عن 404.
- تحقق من canonical وsitemap وrobots.txt لتطابق النطاق المنشور.
- تأكد من أن إعدادات البناء لا تستبعد مجلد المحتوى.
إذا كان الموقع يُنشر عبر سير عمل آلي، راجع حالة المهمة ورسائل الخطأ قبل إعادة تشغيلها؛ تعديل إعدادات عشوائيًا قد يخفي السبب الحقيقي.
قائمة فحص النشر بعد دفع التغييرات
نجاح عملية الدفع إلى Git لا يثبت أن الموقع المنشور يعمل. افتح رابط Pages بعد انتهاء البناء، وجرب الصفحة الرئيسية وصفحات المقالات والموارد الثابتة. عند النشر من مستودع مشروع، انتبه إلى أن المسار قد يتضمن اسم المستودع، لذلك قد تفشل الروابط المطلقة التي تبدأ من الجذر إذا لم تكن مضبوطة للمضيف.
- راجع حالة البناء وسجلات النشر عند ظهور خطأ.
- اختبر الروابط والصور وملفات CSS وJavaScript.
- افتح صفحة داخلية مباشرة في تبويب جديد.
- تحقق من إعداد HTTPS والنطاق المخصص عند استخدامه.
- احتفظ بطريقة تراجع إلى commit معروف عند حدوث مشكلة.
بعد النشر، اختبر نسخة الموقع الفعلية بدل الاكتفاء بالمعاينة المحلية؛ اختلاف المسارات وإعدادات البناء من أكثر أسباب الأعطال شيوعًا.
قائمة تحقق لنشر موقع ثابت بأمان
قبل النشر، افصل بين الملفات المصدرية والنسخة التي تريد إتاحتها للجمهور، وتأكد من أن الفرع أو المجلد المختار في إعدادات Pages هو الصحيح. لا تضع مفاتيح سرية أو ملفات بيئة محلية في مستودع عام، لأن HTML وJavaScript اللذين يصلان إلى المتصفح لا يمكنهما حماية أسرار الخادم.
| المرحلة | التحقق | ما الذي يمنع النشر؟ |
|---|---|---|
| المصدر | الملفات والروابط موجودة في الفرع المقصود | ملفات مفقودة أو تغييرات غير مراجعة |
| المسارات | روابط الصور وCSS تعمل من المسار المنشور | مسارات تعتمد على جهاز المطور |
| البناء | فحوصات المشروع ناجحة عند توفرها | خطأ يمنع إنتاج الموقع |
| المعاينة | الصفحات الأساسية تعمل عبر HTTPS | 404 أو محتوى ناقص أو روابط خاطئة |
| ما بعد النشر | تجربة المستخدم والروابط والبيانات الوصفية | مشكلة لا تظهر في البيئة المحلية |
المسارات النسبية والنشر تحت مسار فرعي
قد يختلف عنوان الموقع في GitHub Pages عن نطاق مخصص أو عن خادم محلي. اختبر روابط تبدأ من الجذر بعناية، وتأكد من أن المسار يشير إلى جذر النشر الفعلي. انتبه إلى حالة الأحرف في أسماء الملفات، لأن اختلافًا صغيرًا قد يعمل على جهاز ولا يعمل على الخادم.
النطاق المخصص وHTTPS
عند ربط نطاق مخصص، تحقق من إعدادات DNS المطلوبة من وثائق GitHub الرسمية، ولا تنسخ قيمًا من مشروع آخر. انتظر حتى تنتهي عملية التحقق وإصدار الشهادة، ثم اختبر الوصول عبر HTTPS والروابط canonical. لا تغيّر DNS أو CNAME لمجرد معالجة مشكلة محتوى أو رابط داخلي.
التحقق بعد النشر
- افتح الصفحة الرئيسية وصفحتين عميقتين مباشرة.
- اختبر الصور والخطوط وملفات CSS وJavaScript من أدوات الشبكة.
- افحص التنقل على الهاتف، والنماذج والروابط الخارجية.
- راجع metadata والمعاينة الاجتماعية عند مشاركة الرابط.
- راقب سجل البناء والتنبيهات، واحتفظ بطريقة تراجع واضحة.
راجع دليل البدء في GitHub Pages وتوثيق النطاق المخصص. اتبع القيم الخاصة بمستودعك ولا تغيّر إعدادات النطاق دون مراجعة السبب والنتيجة.
تشخيص أكثر أخطاء النشر شيوعًا في GitHub Pages
إذا نجح البناء لكن الصفحة المنشورة لا تعمل، ابدأ بتحديد هل المشكلة في مسار النشر أم في الملفات أم في النطاق. افتح سجل البناء، وتحقق من المجلد الذي يتم نشره، ثم افحص طلبات الشبكة لمعرفة إن كانت الصفحة أو ملفات CSS والصور تعيد 404.
صفحة رئيسية تعمل وروابط عميقة تفشل
قد تشير الروابط إلى جذر نطاق مختلف عن المسار الذي ينشر فيه المشروع. اختبر عنوان صفحة عميقة مباشرة، وراجع المسارات النسبية والمطلقة. لا تغير كل الروابط إلى مسارات مطلقة دون فهم بنية النشر.
النطاق وHTTPS
إذا كان النطاق المخصص لا يعمل، تحقق من إعدادات GitHub Pages وDNS وفق الوثائق الحالية. لا تنسخ سجلات DNS من مشروع آخر ولا تعدل إعدادات النطاق أثناء معالجة خطأ محتوى. بعد اكتمال الإعداد، اختبر الوصول عبر HTTPS وتأكد من أن canonical والروابط تشير إلى النطاق الصحيح.
إجراء تراجع عند النشر الخاطئ
احتفظ بفرع أو commit معروف السلامة، وافصل تغييرات المحتوى عن تغييرات الإعدادات. إذا أحدث نشر جديد مشكلة، قارن الملفات التي تغيرت وتراجع عن التغيير المسبب بدل تعديل إعدادات متعددة عشوائيًا. وثّق الحل حتى لا تتكرر المشكلة عند التحديث القادم.
قائمة تحقق قبل وبعد نشر الموقع على GitHub Pages
تعتمد أخطاء النشر كثيرًا على الفرق بين بيئة التطوير ومسار الموقع المنشور. إذا كان الموقع مستضافًا ضمن مستودع مشروع، فقد يكون المسار الأساسي مختلفًا عن نطاق المستخدم، وبالتالي قد تفشل روابط تبدأ من الجذر مثل /assets/app.css. اختبر الروابط النسبية على عنوان المعاينة الفعلي، وافحص وحدة التحكم في المتصفح بحثًا عن ملفات 404 أو أخطاء JavaScript.
تأكد من إعداد مصدر النشر
راجع إعدادات Pages لتعرف هل المصدر فرع ومجلد أم workflow يبني الملفات وينشرها. إذا كان هناك build step، تحقق من أن الأمر ينتهي برمز نجاح وأن مجلد الناتج يحتوي على صفحة الدخول والموارد اللازمة. لا تنشر مجلد المصدر إذا كان الموقع يحتاج إلى بناء، ولا تفترض أن نجاح عملية البناء يعني أن جميع المسارات النهائية صحيحة.
افحص النطاق وHTTPS
عند استخدام نطاق مخصص، راجع سجل DNS المطلوب من مزود الاستضافة وتأكد من أن ملف CNAME - إن كان مستخدمًا - يحتوي الاسم المتوقع فقط. تجنب تغيير سجلات DNS عشوائيًا؛ دوّن القيم الحالية وتحقق من تعليمات GitHub الرسمية قبل تعديلها. بعد تفعيل HTTPS، افحص أن الصور والأنماط والبرامج النصية لا تُحمّل من مصادر HTTP غير آمنة، وأن النسخة النهائية لا تحتوي على روابط معاينة مؤقتة.
اختبر النشر من منظور الزائر
افتح الصفحة الرئيسية وصفحات عميقة مباشرة، ثم جرّب التحديث وإعادة التحميل والتنقل والروابط الداخلية. افحص صفحة 404، والعناوين والوصف وcanonical، وملف sitemap إذا كان المشروع يستخدمه. راجع السلوك على الهاتف، ولا تعتمد على نسخة مخزنة في المتصفح؛ افتح نافذة خاصة أو امسح الذاكرة المؤقتة للتحقق من آخر نشر.
إذا فشل النشر، اقرأ سجل workflow أو سجل البناء وحدد أول خطأ حقيقي بدل إصلاح التحذيرات عشوائيًا. المرجع الأوثق هو توثيق GitHub Pages الرسمي، لأنه يشرح قيود المسارات والنطاقات ومصادر النشر بحسب إعداد المستودع.
تمييز مشكلة النشر عن مشكلة التخزين المؤقت
إذا كان آخر إصدار لا يظهر رغم نجاح النشر، تحقق أولًا من رابط المعاينة وسجل البناء، ثم افتح الصفحة في نافذة خاصة واطلب تحديثًا دون استخدام الذاكرة المؤقتة. افحص أيضًا ما إذا كانت خدمة وسيطة أو متصفحًا يحتفظ بملف قديم. لا تعدّل DNS أو إعدادات النطاق لمجرد أن المتصفح يعرض نسخة قديمة؛ حدد الطبقة المسؤولة بالدليل قبل تغيير الإعدادات.
دوّن إعدادات النشر المهمة في مستند المشروع دون تضمين أسرار، واذكر أين تُراجع سجلات البناء وكيف تُختبر نسخة المعاينة قبل النشر النهائي.
الخلاصة
الخلاصة: تحقق من مصدر النشر والمسارات وسجل البناء، ثم اختبر الروابط والموارد على النسخة المنشورة. افصل إصلاح المحتوى عن تغييرات النطاق وDNS، واحتفظ بخطة تراجع.