گیتهاب پیجز با جکیل: چرا سایت شما بعد از دیپلوی سفید میشود؟
آموزش -complete-guide گیت هاب درباره گیت هاب پیجز با جکیل به شما کمک میکند تا با درک عمیق مفاهیم پیشرفته، گردشکارهای حرفهای را پیادهسازی کنید، خطاهای رایج را شناسایی و رفع نمایید و بهرهوری تیم توسعه را به شکل چشمگیری افزایش دهید.
GitHub Pages یک سرویس میزبانی استاتیک است که فایلهای HTML، CSS و JavaScript را مستقیماً از مخزن GitHub سرو میکند. Jekyll یک موتور تولید سایت استاتیک است که با Pages یکپارچه شده و به شما اجازه میدهد از Markdown، قالبهای Liquid و ساختار پوشهای منظم، یک سایت کامل بسازید. ترکیب این دو، راهی کمهزینه و سریع برای انتشار وبلاگ، مستندات پروژه و سایت شخصی است. اما دامهای فنی مشخصی هم دارد: خطاهای build که صفحهی سفید تحویل میدهند، تفاوت بین github.io و دامنهی سفارشی، محدودیتهای پلاگین و رفتار متفاوت Jekyll در محیط محلی و محیط GitHub. این نوشته از ساختار مخزن و پیکربندی _config.yml تا عیبیابی خطاهای رایج و بهینهسازی برای سئو را پوشش میدهد.
اولین باری که یک سایت Jekyll روی GitHub Pages راهاندازی کردم، بعد از چند ساعت کار روی قالب، صفحهی سفید تحویل گرفتم. هیچ خطای واضحی نبود، فقط یک صفحهی خالی و یک لاگ مبهم. تجربهی آن روز به من یاد داد که بزرگترین چالش GitHub Pages با Jekyll، نوشتن محتوا نیست؛ شفافسازی رفتار build در محیط GitHub است.
GitHub Pages و Jekyll؛ چرا این ترکیب محبوب است
GitHub Pages امکان میزبانی سایت استاتیک را مستقیماً از یک مخزن فراهم میکند. این سرویس رایگان است، پشتیبانی از HTTPS دارد و میتواند روی دامنهی سفارشی کار کند. Jekyll هم یک موتور تولید سایت استاتیک است که فایلهای Markdown را به HTML تبدیل میکند و با GitHub Pages یکپارچگی مستقیم دارد.
چند مزیت اصلی این ترکیب:
- بدون سرور: نیازی به مدیریت زیرساخت نیست.
- رایگان: حتی برای پروژههای عمومی و شخصی.
- نسخهبندی با Git: محتوا و کد در یک مخزن.
- پشتیبانی از Markdown: نوشتن محتوا بدون HTML.
- قالبهای Liquid: انعطاف در طراحی بدون پیچیدگی.
- یکپارچگی با GitHub Actions: امکان سفارشیسازی build.
در مقابل، محدودیتهایی هم دارد: نبود پایگاه داده، محدودیت در پلاگینها، نبود اجرای سمت سرور و رفتار متفاوت build در محیط GitHub با محیط محلی. شناخت این محدودیتها بخشی از طراحی است، نه مانع استفاده. اصول کلی انتشار سایت استاتیک با آنچه در چگونه یک سایت وردپرسی را از صفر راهاندازی کنیم؟ توضیح داده شده، از نظر معماری متفاوت است.
GitHub Pages یک میزبان ساده است، اما سادگی آن بهمعنای سادگی رفتار build نیست.
راهاندازی مخزن و ساختار پوشهها
ساختار پوشهی یک پروژهی Jekyll روی GitHub Pages از یک الگوی مشخص پیروی میکند:
my-site/
├── _config.yml
├── _posts/
│ └── 2025-03-14-first-post.md
├── _layouts/
│ ├── default.html
│ └── post.html
├── _includes/
│ ├── header.html
│ └── footer.html
├── _sass/
├── assets/
│ ├── css/
│ └── images/
├── index.md
├── about.md
└── Gemfile
هر پوشهی با پیشوند _ توسط Jekyll پردازش میشود و مستقیماً در خروجی نهایی قرار نمیگیرد. پوشهی _posts محل نوشتههاست، _layouts قالبهای اصلی، _includes اجزای قابل استفادهی مجدد و _sass محل فایلهای Sass است.
انتخاب نام مخزن مهم است: اگر مخزن با نام username.github.io باشد، سایت روی ریشهی آن دامنه منتشر میشود. اگر نام دیگری باشد، سایت روی مسیر username.github.io/repo-name/ منتشر میشود و این مسیر باید در تنظیمات baseurl لحاظ شود.
برای راهاندازی سریع، از تمهای آماده استفاده کنید. اما برای پروژههای جدی، ساخت قالب اختصاصی کنترل بیشتری میدهد. اصول سازماندهی فایلها در ساختار فایلهای یک قالب استاندارد وردپرس از زاویهی مشابه بررسی شده است.
پیکربندی _config.yml و تنظیمات کلیدی
فایل _config.yml قلب تنظیمات Jekyll است. چند تنظیم کلیدی:
title: My Jekyll Site
description: A site about web development
url: "https://example.com"
baseurl: ""
theme: minima
markdown: kramdown
highlighter: rouge
plugins:
- jekyll-feed
- jekyll-seo-tag
- jekyll-sitemap
permalink: /:year/:month/:day/:title/
تنظیم url و baseurl از پرتکرارترین منشأ خطاهای build است. اگر این دو بهدرستی تنظیم نشوند، لینکهای داخلی سایت در محیط GitHub به مسیرهای اشتباه اشاره میکنند و نتیجه، صفحهی 404 یا صفحهی سفید است.
تنظیم permalink ساختار URL نوشتهها را تعیین میکند. مقدار پیشفرض Jekyll تاریخ کامل را در URL میگذارد. اما برای سئو، ساختار کوتاهتر و معنادارتر مثل /:title/ یا /blog/:title/ توصیه میشود. اصول این تصمیم در URL را حرفهای بسازید: ساختار و سئو بهتفصیل بررسی شده است.
پلاگینهای تعریفشده در _config.yml باید در whitelist GitHub Pages باشند یا از طریق GitHub Actions اجرا شوند. این محدودیت یکی از رایجترین علتهای شکست build در محیط GitHub است.
Front Matter و ساختار نوشتهها
هر نوشتهی Jekyll با یک بلوک Front Matter آغاز میشود که فرادادهی آن را تعریف میکند:
---
layout: post
title: "چگونه با Jekyll سایت شخصی بسازیم"
date: 2025-03-14 10:00:00 +0330
categories: [tutorial, jekyll]
tags: [static-site, github-pages]
image: /assets/images/jekyll-cover.jpg
---
متن نوشته در اینجا قرار میگیرد.
این بلوک به Jekyll میگوید از کدام قالب استفاده کند، عنوان نوشته چیست و در چه تاریخ منتشر میشود. نام فایل باید با الگوی YYYY-MM-DD-title.md مطابقت داشته باشد تا Jekyll آن را بهعنوان نوشته تشخیص دهد.
نکتهی مهم در مورد منطقهی زمانی (timezone): اگر تاریخ با +0330 تنظیم شود، Jekyll آن را بر اساس همان منطقهی زمانی پردازش میکند. اما اگر منطقهی زمانی مشخص نشود، Jekyll از UTC استفاده میکند و ممکن است نوشتهای که امروز نوشتهاید، فردا منتشر شود. این رفتار گیجکننده در پروژههای واقعی چند بار باعث سردرگمی شده است.
Front Matter یک بلوک سادهی YAML است، اما کوچکترین اشتباه در آن میتواند کل نوشته را از فهرست خارج کند.
Liquid templating و ساخت قالبها
Liquid زبان قالببندی Jekyll است که با آن میتوانید منطق نمایش را تعریف کنید. سه ساختار اصلی:
- Objects: نمایش متغیرها با
{{ ... }}. - Tags: کنترل جریان با
{% ... %}. - Filters: تغییر خروجی با
|.
{% for post in site.posts limit:5 %}
{{ post.title }}
{{ post.excerpt | strip_html | truncate: 160 }}
{% endfor %}
فیلتر relative_url در Jekyll 4.x اضافه شده و از مسیر baseurl استفاده میکند. اگر آن را نادیده بگیرید، لینکها در سایتهایی که زیر مسیر هستند (مثل username.github.io/repo) به مسیر اشتباه اشاره میکنند.
ساختار قالبها معمولاً از یک قالب پایه (default.html) تشکیل میشود که شامل اجزای مشترک است و قالبهای دیگر مثل post.html از آن ارثبری میکنند:
---
layout: default
---
{{ page.title }}
{{ content }}
این ساختار، نگهداری را سادهتر میکند. تغییرات در قالب پایه بهطور خودکار در همهی صفحات اعمال میشود. اصول این نوع قالببندی با آنچه در قالب وردپرس چایلد چیست و چه زمانی به آن نیاز داریم؟ توضیح داده شده، از نظر مفهومی همراستاست.
پلاگینها؛ چه چیزی مجاز است و چه چیزی نیست
GitHub Pages فقط پلاگینهایی را اجرا میکند که در whitelist رسمی آن باشند. این محدودیت به دلایل امنیتی اعمال شده و رایجترین پلاگینهای مجاز شامل موارد زیر است:
jekyll-seo-tagjekyll-sitemapjekyll-feedjekyll-paginatejekyll-redirect-fromjekyll-github-metadatajekyll-relative-linksjekyll-optional-front-matter
اگر پلاگینی در whitelist نباشد، دو راه دارید: آن را حذف کنید یا از GitHub Actions برای build استفاده کنید. گزینهی دوم انعطاف کامل میدهد، اما نیازمند تنظیم workflow است.
یکی از رایجترین پلاگینهایی که کاربران میخواهند استفاده کنند و در whitelist نیست، پلاگینهای مبتنی بر Ruby سفارشی هستند. برای این موارد، مهاجرت به GitHub Actions راهحل استاندارد است. اصول این مهاجرت با آنچه در GitHub Actions راهنمای خودکارسازی گردش کار توضیح داده شده، همراستاست.
فرآیند build در GitHub و تفاوت آن با محیط محلی
یکی از بزرگترین دامهای Jekyll، تفاوت رفتار build در محیط محلی و محیط GitHub است. علت این تفاوت چند چیز است:
- نسخهی Jekyll: GitHub ممکن است از نسخهای متفاوت از Jekyll استفاده کند.
- نسخهی Ruby: تفاوتها در رفتار gemها.
- پلاگینهای whitelist شده: پلاگینهایی که محلی کار میکنند ممکن است در GitHub نادیده گرفته شوند.
- نحوهی پردازش فایلهای خارجی: فایلهایی که با
excludeمشخص نشدهاند ممکن است در خروجی نهایی ظاهر شوند.
برای پیشگیری از این تفاوتها، از یک محیط محلی همنسخه با GitHub استفاده کنید. ابزار bundle exec jekyll serve با فایل Gemfile و Gemfile.lock نسخهی Jekyll را دقیق تعیین میکند. اگر فایل Gemfile وجود داشته باشد، GitHub Pages نسخهی Jekyll را بر اساس آن انتخاب میکند.
نکتهی عملی دیگر: اگر build در GitHub شکست بخورد، پیام خطا در تب Actions نمایش داده میشود. این پیام معمولاً مبهم است، اما با بررسی دقیق میتوان علت را تشخیص داد. رایجترین علتها: نبود پلاگین، خطای YAML در Front Matter و مسیر نادرست در baseurl. اصول عیبیابی مشابه در رفع خطاهای رایج Git راهنمای کاربردی و خطای نصب قالب در وردپرس نیز بررسی شده است.
دامنهی سفارشی و HTTPS
اتصال دامنهی سفارشی به GitHub Pages چند مرحله دارد:
- یک فایل
CNAMEدر ریشهی مخزن با نام دامنه ایجاد کنید. - در پنل DNS دامنه، یک رکورد
AیاCNAMEبه مقصد GitHub تنظیم کنید. - در تنظیمات مخزن، در بخش Pages، دامنهی سفارشی را وارد کنید.
- گزینهی Enforce HTTPS را فعال کنید.
رکوردهای A پیشنهادی GitHub برای ریشهی دامنه، آدرسهای مشخصی هستند که در مستندات رسمی آمده است. برای زیردامنهها، استفاده از CNAME به username.github.io انتخاب درست است.
نکتهی مهم در HTTPS: اگر دامنهی شما از طریق CDN مثل Cloudflare سرو میشود، تنظیمات SSL باید با GitHub Pages هماهنگ باشد. حالت «Flexible SSL» در Cloudflare میتواند به حلقهی ریدایرکت منجر شود. راهحل، حالت «Full» یا «Full (Strict)» است. اصول این تنظیمات در نقد Cloudflare: آیا لایه امنیتی اول برای هر سایت است؟ بررسی شده است.
در پروژههایی که روی سئو حساس هستند، مهاجرت به دامنهی سفارشی باید با ریدایرکتهای درست انجام شود. تغییر دامنه بدون ریدایرکت، اعتبار صفحات را از بین میبرد. اصول این کار با آنچه در چگونه دامنه سایت را بدون افت سئو تغییر دهیم؟ توضیح داده شده، همراستاست.
اجرای Jekyll با GitHub Actions بهجای build داخلی
برای رهایی از محدودیتهای whitelist و کنترل کامل build، از GitHub Actions استفاده کنید. یک workflow ساده برای build و deploy:
name: Build and Deploy
on:
push:
branches: [main]
permissions:
contents: read
pages: write
id-token: write
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: ruby/setup-ruby@v1
with:
ruby-version: "3.3"
bundler-cache: true
- run: bundle exec jekyll build
- uses: actions/upload-pages-artifact@v3
deploy:
needs: build
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- uses: actions/deploy-pages@v4
id: deployment
این workflow به شما اجازه میدهد از هر پلاگین Jekyll استفاده کنید و نسخهی Ruby و Jekyll را دقیق تعیین کنید. تفاوت اصلی با build داخلی، کنترل کامل بر محیط است. اصول این نوع خودکارسازی با آنچه در گیتهاب اکشنز توضیح داده شده، همراستاست.
نکتهی مهم در امنیت: permissions باید حداقل لازم باشد. برای انتشار در Pages، به pages: write و id-token: write نیاز دارید، اما نه بیشتر. اصول مدیریت دسترسی در مدیریت سکرتها در گیتهاب اکشنز بررسی شده است.
سئو و بهینهسازی سایت Jekyll روی Pages
سایتهای Jekyll بهطور طبیعی سریع هستند، اما سئو نیازمند اقدامات مشخص است:
- پلاگین jekyll-seo-tag: تولید متاتگها و OpenGraph بهطور خودکار.
- پلاگین jekyll-sitemap: تولید sitemap.xml برای موتورهای جستوجو.
- پلاگین jekyll-feed: تولید فید RSS.
- URL معنادار: با تنظیم
permalinkمناسب. - تصاویر بهینه: با فرمت WebP و ابعاد مناسب.
- دادهی ساختیافته: با JSON-LD در قالبها.
- سرعت بارگذاری: Jekyll بهطور طبیعی سریع است، اما حجم CSS و JS میتواند آن را کند کند.
یکی از مزایای Jekyll برای سئو، تولید HTML استاتیک است. موتورهای جستوجو بهسادگی محتوای آن را میخوانند. اما اگر ساختار URL و متاتگها درست نباشد، این مزیت از بین میرود. اصول کلی سئو فنی در استانداردهای سئو فنی وب بررسی شده است.
برای Core Web Vitals، سایتهای Jekyll معمولاً عملکرد خوبی دارند. اما دو نکته را جدی بگیرید: اندازهی تصاویر و حجم فونتها. اگر این دو کنترل شوند، LCP و CLS در محدودهی قابل قبول خواهند بود. اصول این بهینهسازی در چگونه Core Web Vitals را بهبود دهیم؟ بهتفصیل آمده است.
سایت Jekyll سریع متولد میشود؛ وظیفهی شما این است که سریع بماند.
اشتباهات رایج در GitHub Pages با Jekyll
- تنظیم نادرست baseurl: شکستن لینکهای داخلی در سایتهای زیرمسیر.
- استفاده از پلاگین خارج از whitelist: build بدون هشدار واضح شکست میخورد.
- نادیده گرفتن نسخهی Jekyll: تفاوت رفتار بین محلی و GitHub.
- Front Matter ناقص: نوشتهای که در فهرست ظاهر نمیشود.
- عدم تنظیم timezone: تاریخ انتشار اشتباه.
- نادیده گرفتن فایل CNAME: از دست رفتن دامنهی سفارشی پس از deploy.
- commit کردن پوشهی _site: اضافه کردن فایلهای تولیدشده به مخزن.
- نادیده گرفتن HTTPS: نبود ریدایرکت HTTP به HTTPS.
- حذف فایل Gemfile.lock: نسخهی نامشخص gemها.
- نبود فایل .nojekyll: در پروژههایی که از فایلهای با پیشوند _ استفاده میکنند.
- نادیده گرفتن امنیت مخزن: ذخیرهی سکرتها در فایلهای تنظیمات.
- نبود بازبینی خروجی: انتشار صفحهی سفید بدون بررسی پیش از merge.
بسیاری از این اشتباهات با یک بازبینی ساده پیش از push قابل پیشگیری هستند. اگر روی پروژهی حساس کار میکنید، استفاده از یک شاخهی preview برای تست تغییرات قبل از merge به شاخهی اصلی، توصیهی جدی است. اصول این نوع workflow در برنچ در Git راهنمای مدیریت شاخهها توضیح داده شده است.
پرسشهای پرتکرار درباره GitHub Pages با Jekyll
چرا سایت Jekyll من بعد از deploy سفید است؟ معمولاً بهدلیل خطای build در GitHub، تنظیم نادرست baseurl یا نبود پلاگین ضروری. ابتدا تب Actions را بررسی کنید.
آیا میتوانم از پلاگینهای Jekyll دلخواه استفاده کنم؟ در build داخلی فقط پلاگینهای whitelist مجاز هستند. برای پلاگینهای دیگر، از GitHub Actions استفاده کنید.
تفاوت GitHub Pages با Jekyll و بدون Jekyll چیست؟ بدون Jekyll، فایلهای HTML را مستقیماً push میکنید. با Jekyll، فایلهای Markdown به HTML تبدیل میشوند.
چطور دامنهی سفارشی را اتصال دهم؟ با فایل CNAME در ریشهی مخزن، تنظیم DNS و فعالسازی دامنه در تنظیمات مخزن.
آیا HTTPS روی GitHub Pages رایگان است؟ بله، برای دامنههای سفارشی و زیردامنههای github.io. فعالسازی از تنظیمات مخزن.
چطور زمان build را کاهش دهم؟ با cache کردن gemها، محدود کردن پلاگینها و بهینهسازی تعداد فایلهای پردازششده.
آیا میتوانم سایت را روی دامنهی اصلی منتشر کنم؟ بله، با مخزن با نام username.github.io. برای دامنهی سفارشی، تنظیم CNAME و DNS.
آیا GitHub Pages برای فروشگاه آنلاین مناسب است؟ برای فروشگاه ساده با پرداخت خارجی ممکن است، اما بدون backend مناسب نیست. اصول فروشگاهها در چرا ووکامرس برای فروشگاههای کوچک ایدهآل است؟ بررسی شده است.
آیا میتوانم از Jekyll برای مستندات پروژه استفاده کنم؟ بله، یکی از رایجترین کاربردهای Jekyll مستندات پروژه است.
چطور از انتشار ناخواسته فایلها جلوگیری کنم؟ با تنظیم exclude در _config.yml و آگاهی از پوشههایی که Jekyll نادیده میگیرد.
آیا GitHub Pages از SEO پشتیبانی میکند؟ بله، با پلاگینهای مناسب و تنظیم ساختار URL. اصول آن در چرا وب استانداردها مهم هستند؟ از زاویهی مکمل بررسی شده است.
لایهی مهندسی و تصمیمهای معماری
از منظر معماری سیستمهای میزبانی استاتیک، GitHub Pages یک CDN جهانی روی مخزن Git است. فایلهای خروجی Jekyll به لبههای شبکه توزیع میشوند و به کاربر نزدیکترین نقطه سرو میشوند. این معماری، تأخیر پایین و مقیاسپذیری بالا را فراهم میکند، اما محدودیتهای خودش را دارد: نبود پردازش سمت سرور، نبود کنترل بر هدرهای HTTP و محدودیت در routing.
در سطح pipeline، تفاوت بین build داخلی و GitHub Actions یک تصمیم معماری است. build داخلی برای پروژههای ساده کافی است و نگهداری کمتری دارد. GitHub Actions کنترل کامل میدهد اما نیازمند نگهداری بیشتر است. انتخاب درست به پیچیدگی پروژه و تخصص تیم بستگی دارد.
در لایهی کش، GitHub Pages از هدرهای cache بهطور پیشفرض استفاده میکند. برای کنترل بیشتر، میتوان از Cloudflare یا سرویس CDN دیگری بهعنوان لایهی میانی استفاده کرد. اصول این معماری با آنچه در مقایسه سرویسهای CDN: کدام انتخاب برای سایت شما بهتر است؟ توضیح داده شده، همراستاست.
در لایهی امنیت، سایتهای Jekyll بهدلیل نبود backend، سطح حملهی کمتری دارند. اما این بهمعنای امنیت مطلق نیست. اگر محتوا با APIهای خارجی ترکیب شود یا از سرویسهای third-party استفاده شود، ریسک برمیگردد. اصول کلی در بهترین روشهای امنیت وب کدامند؟ بررسی شده است.
در نهایت، از منظر مقیاس، GitHub Pages محدودیتهایی در پهنای باند و تعداد درخواست دارد. برای سایتهای با ترافیک بالا، ممکن است به CDN اضافه یا سرویس میزبانی استاتیک اختصاصی نیاز باشد. این تصمیم معماری معمولاً در فاز رشد مطرح میشود. 🧩
از منظر تجربهی توسعهدهنده، Jekyll یک محیط ساده اما قدرتمند برای تولید محتوا است. با ترکیب Markdown و Liquid، میتوان محتوای پیچیده را بدون پیچیدگی فنی زیاد تولید کرد. این ویژگی، Jekyll را برای مستندسازی و وبلاگنویسی فنی بسیار مناسب میکند. 📊
بستن بحث
GitHub Pages با Jekyll یک راهحل ساده و کمهزینه برای میزبانی سایت استاتیک است که اگر با شناخت دامها و محدودیتها استفاده شود، نتایج حرفهای میدهد. کلید موفقیت در سه چیز است: تنظیم درست _config.yml، آگاهی از تفاوتهای محیط محلی و GitHub، و استفاده از GitHub Actions برای پروژههای پیچیده.
اگر تازه شروع کردهاید، از یک تم آماده استفاده کنید و ساختار را بهتدریج سفارشی کنید. اگر روی پروژهی جدی کار میکنید، از ابتدا ساختار پوشه و پیکربندی را اصولی بچینید. اگر به محدودیت پلاگین برخوردید، مهاجرت به Actions را در نظر بگیرید.
اگر تجربهای از پیادهسازی سایت Jekyll روی GitHub Pages دارید، برایم جالب است بدانید کدام چالش بیشترین زمان را گرفت. تجربهتان را در دیدگاهها بنویسید؛ بهخصوص اگر راهحل جایگزینی برای مدیریت build یا دامنه پیدا کردهاید.