آموزش GitHub Pages؛ انتشار سایت استاتیک رزومه از مخزن تا رفع خطای ۴۰۴

یک صفحه رزومه با HTML و CSS ساخته‌اید، اما هنوز فقط روی رایانه خودتان باز می‌شود؟ GitHub Pages می‌تواند فایل‌های استاتیک همان پروژه را از یک مخزن به وب‌سایتی با نشانی عمومی تبدیل کند. در این راهنما فرض می‌کنیم فایل‌های سایت از قبل آماده‌اند و می‌خواهیم آن‌ها را بدون سرور سمت‌کاربر یا خرید دامنه منتشر کنیم. سناریو آموزشی است؛ هیچ سایت یا استقرار واقعی در این مقاله انجام نشده و نتیجه‌ای به‌عنوان تجربه آزمایش‌شده ادعا نمی‌شود.

اگر هنوز صفحه‌ای نساخته‌اید، از راهنمای ساخت اولین صفحه HTML و CSS شروع کنید. در اینجا تمرکز بر انتشار و عیب‌یابی است، نه طراحی قالب. پیش از بارگذاری هر فایل، به یاد داشته باشید Pages سایت را عمومی می‌کند؛ حتی اگر طرح حساب شما انتشار از مخزن خصوصی را مجاز بداند، محتوای منتشرشده را محرمانه فرض نکنید. این هشدار در مستندات رسمی GitHub آمده است.

پیش‌نیاز: سایت استاتیک و مخزن مناسب

GitHub Pages فایل‌های HTML، CSS و JavaScript یا خروجی ساخته‌شده یک ابزار تولید سایت استاتیک را منتشر می‌کند. اجرای PHP، Python یا پایگاه داده روی خود Pages انجام نمی‌شود. اگر فرم شما به ذخیره اطلاعات، ورود کاربر یا پرداخت نیاز دارد، صرف انتشار فایل‌ها آن قابلیت سمت سرور را فراهم نمی‌کند. تعریف رسمی GitHub Pages آن را خدمت میزبانی سایت استاتیک توصیف می‌کند و راهنمای ساخت سایت محدودیت زبان‌های سمت سرور را توضیح می‌دهد.

برای نمونه، پوشه پروژه رزومه شما ممکن است یک فایل ورودی به نام index.html، یک پوشه تصویر و یک فایل CSS داشته باشد. قبل از انتشار، صفحه را محلی باز کنید و لینک‌های منو، متن جایگزین تصاویر، خوانایی در موبایل و اطلاعات تماس را بررسی کنید. رمز عبور، کلید API، فایل تنظیمات خصوصی یا داده مشتری را در فایل‌ها و تاریخچه مخزن قرار ندهید. ساخت مخزن عمومی برای حساب رایگان، به معنی عمومی‌شدن فایل‌های مخزن نیز هست.

سایت شخصی یا سایت یک پروژه؟

دو نوع نشانی پیش‌فرض مهم است. برای سایت حساب کاربری یا سازمان، نام مخزن باید به شکل نام کاربری و پسوند .github.io باشد و نشانی اصلی نیز زیر همان دامنه قرار می‌گیرد. برای سایت یک پروژه معمولی، نشانی پیش‌فرض یک بخش اضافه با نام مخزن دارد؛ نمونه مفهومی آن username.github.io/portfolio/ است. بنابراین مسیری که روی رایانه از ریشه کار می‌کند ممکن است در سایت پروژه به مسیر اشتباه اشاره کند. مقایسه رسمی دو نوع سایت را پیش از نام‌گذاری مخزن ببینید.

۱. فایل‌های آماده را در جای درست مخزن بگذارید

یک مخزن تازه برای سایت آزمایشی بسازید یا مخزن پروژه موجود را انتخاب کنید. اگر هدف، سایت شخصی با نشانی ریشه است، نام‌گذاری ویژه حساب را رعایت کنید؛ اگر هدف انتشار همین پروژه رزومه است، نامی ساده و پایدار برای مخزن بگذارید. در حساب‌های رایگان، برای استفاده معمول از Pages مخزن عمومی لازم است؛ شرایط طرح‌های دیگر را از مستندات جاری GitHub بررسی کنید. در زمان ساخت مخزن، داشتن README می‌تواند توضیح پروژه را از فایل‌های سایت جدا کند.

برای انتشار مستقیم از شاخه، فایل ورودی باید در سطح بالای پوشه‌ای باشد که به‌عنوان منبع انتشار انتخاب می‌کنید. اگر منبع main و پوشه /(root) است، index.html را در ریشه همان شاخه بگذارید؛ اگر منبع پوشه /docs است، آن فایل باید داخل docs باشد. قرار دادن آن در پوشه‌ای دیگر و انتخاب ریشه، از خطاهای رایج است. راهنمای ایجاد سایت GitHub جای فایل ورودی را برای هر منبع توضیح می‌دهد.

نام فایل را دقیق بررسی کنید: index.html با حروف کوچک. تغییر حروف، پسوند یا قرارگیری فایل در پوشه اشتباه می‌تواند باعث ۴۰۴ شود. برای پروژه‌های کوچک لازم نیست از همان ابتدا workflow سفارشی بنویسید؛ مسیر انتشار از شاخه ساده‌تر است. اگر ابزار ساختی مانند فریم‌ورک دارید که ابتدا خروجی استاتیک تولید می‌کند، سپس درباره workflow یا روش استقرار متناسب با همان ابزار تصمیم بگیرید. این مقاله فقط مسیر فایل‌های استاتیک آماده را دنبال می‌کند.

۲. منبع انتشار Pages را تنظیم کنید

در مخزن GitHub به Settings بروید و از بخش Pages، زیر Build and deployment گزینه Deploy from a branch را برای Source انتخاب کنید. سپس شاخه‌ای را انتخاب کنید که فایل‌ها در آن قرار دارند؛ برای مثال main. در انتخاب پوشه، /(root) یا /docs را دقیقاً مطابق جای فایل ورودی تعیین و تنظیم را ذخیره کنید. این مراحل در مستندات رسمی منبع انتشار آمده‌اند.

گزینه GitHub Actions نیز برای ساخت و انتشار سفارشی وجود دارد، اما انتخاب آن بدون workflow مناسب ممکن است سایت ساده شما را منتشر نکند. برای HTML و CSS آماده، اول مسیر شاخه را به نتیجه برسانید. اگر بعداً پروژه‌تان به مرحله build نیاز پیدا کرد، می‌توانید workflow را با فایل خروجی درست طراحی کنید. در هر دو حالت، صرف انتخاب یک گزینه به معنی آماده‌بودن سایت نیست؛ وضعیت اجرای استقرار را بررسی کنید.

بعد از ذخیره تنظیم، چه چیزی را ببینیم؟

در همان بخش Pages نشانی و گزینه Visit site را بررسی کنید. ممکن است انتشار تغییرات فوراً در مرورگر دیده نشود؛ مستندات GitHub می‌گوید انتشار پس از push می‌تواند چند دقیقه زمان ببرد. اگر نشانی هنوز آماده نیست، پیش از دست‌کاری بی‌هدف فایل‌ها، اجرای مربوط به ساخت و استقرار را در بخش Actions یا پیام‌های Pages ببینید. خطای build، نبود فایل ورودی یا انتخاب شاخه نادرست، مسئله‌های متفاوتی‌اند و هر کدام راه‌حل خاص دارند.

۳. نشانی عمومی و مسیر دارایی‌ها را آزمایش کنید

پس از اعلام موفقیت استقرار، نشانی دقیق ارائه‌شده در Pages را در پنجره خصوصی باز کنید. اول صفحه اصلی را ببینید، سپس منو، لینک‌های پروژه‌ها، عکس‌ها، فونت‌ها و CSS را کنترل کنید. مشاهده تصویر در پیش‌نمایش محلی کافی نیست؛ مسیر فایل در نشانی سایت پروژه ممکن است به علت بخش نام مخزن شکسته باشد. اگر صفحه HTML باز می‌شود ولی ظاهرش بدون CSS است، مسیر فایل CSS را در صفحه و محل آن را در مخزن با هم مقایسه کنید.

در سایت پروژه‌ای با مسیر اضافی مانند /portfolio/، لینکی که از ابتدای دامنه شروع می‌شود ممکن است به جای پوشه پروژه به ریشه دامنه اشاره کند. برای فایل‌های داخل همان پروژه، مسیرهای نسبیِ سنجیده‌شده یا تنظیم پایه مناسب ابزار ساخت را انتخاب کنید. نام پوشه و حروف بزرگ/کوچک فایل‌ها را نیز یکسان نگه دارید؛ تفاوتی که روی یک سیستم محلی پنهان می‌ماند، در نشانی منتشرشده ممکن است آشکار شود. هر تصویر و لینک را روی URL نهایی، نه فقط روی فایل محلی، باز کنید.

برای نمونه رزومه، از صفحه اصلی به یک پروژه بروید و دوباره به صفحه اول برگردید. اگر لینک «تماس» دارید، مطمئن شوید به نشانی درست می‌رود و اطلاعات شخصی ناخواسته منتشر نشده است. در موبایل، منو، خوانایی متن و عرض تصاویر را ببینید. اگر تازه چینش را طراحی می‌کنید، راهنمای نمونه‌سازی پورتفولیو در فیگما برای فکرکردن به جریان صفحه پیش از انتشار مفید است؛ اما نمونه بصری، جای آزمون URL واقعی را نمی‌گیرد.

۴. خطای ۴۰۴ را به ترتیب علت‌ها بررسی کنید

اگر صفحه اصلی ۴۰۴ است، نخست مطمئن شوید همان نشانی‌ای را باز کرده‌اید که Pages نشان می‌دهد. سپس وضعیت workflow استقرار را ببینید؛ اگر اجرا شکست خورده، هنوز چیزی برای نمایش وجود ندارد. اگر اجرا موفق بوده، شاخه و پوشه منبع را با محل واقعی فایل ورودی تطبیق دهید. نام index.html باید دقیق و به حروف کوچک باشد. این موارد در راهنمای رسمی رفع ۴۰۴ GitHub Pages فهرست شده‌اند.

اگر فقط صفحه‌های داخلی یا تصویرها ۴۰۴ می‌شوند، مشکل احتمالاً در مسیر لینک‌هاست، نه الزاماً در فعال‌سازی Pages. نشانی مقصد را از نوار آدرس کپی و با ساختار پوشه منبع مقایسه کنید. آیا نام مخزن در مسیر سایت پروژه جا افتاده است؟ آیا نام فایل در مخزن با حروف متفاوت ثبت شده؟ آیا فایل اصلاً در شاخه منتخب وجود دارد؟ یک مورد را اصلاح کنید، تغییر را ثبت و پس از استقرار دوباره همان URL را بیازمایید. چند تغییر هم‌زمان، تشخیص علت را سخت می‌کند.

چک‌لیست کوتاه عیب‌یابی

1. نشانی را از Settings → Pages → Visit site باز کنید، نه از حدس خود درباره URL.
2. وضعیت اجرای استقرار را بررسی کنید و پیام خطا را با فایل یا شاخه مرتبط تطبیق دهید.
3. شاخه و پوشه منبع را با جای واقعی index.html مقایسه کنید.
4. حروف نام فایل، پسوند و مسیر تصویر/CSS را با مخزن و URL نهایی یکسان کنید.
5. برای سایت پروژه، بخش نام مخزن در مسیر را در لینک‌های داخلی لحاظ کنید.
6. پس از هر اصلاح محدود، منتظر اتمام استقرار بمانید و در پنجره خصوصی دوباره باز کنید.

اگر دامنه سفارشی اضافه کرده‌اید، تنظیمات DNS و دامنه هم به فهرست بررسی وارد می‌شوند. برای شروع رزومه، بهتر است ابتدا نشانی پیش‌فرض GitHub را سالم کنید و بعد دامنه سفارشی را جداگانه تنظیم کنید؛ این کار دو منبع خطا را از هم تفکیک می‌کند.

پیش از اشتراک‌گذاری رزومه، این کنترل‌ها را انجام دهید

• مخزن و خروجی سایت هیچ رمز، توکن، داده مشتری یا فایل خصوصی ندارند.
• عنوان صفحه، معرفی کوتاه، نقش شما و راه تماس عمومی درست و به‌روز است.
• هر پروژه یک توضیح روشن از مسئله، نقش شما و لینک قابل‌دسترسی دارد؛ نتیجه آزمون‌نشده را به‌عنوان دستاورد قطعی ننوشته‌اید.
• تصاویر حق استفاده دارند، اندازه مناسب‌اند و در موبایل بدون برش ناخواسته دیده می‌شوند.
• لینک‌ها، CSS، فونت‌ها و تصویرها روی URL عمومی با پنجره خصوصی آزموده شده‌اند.
• نشانی نهایی را همان‌طور که در Pages نمایش داده می‌شود ثبت کرده‌اید تا پس از تغییر نام مخزن، لینک‌های رزومه از کار نیفتند.

این کنترل‌ها انتشار را به یک خروجی قابل ارائه تبدیل می‌کنند. GitHub Pages به‌تنهایی کیفیت محتوا، دسترس‌پذیری یا دیده‌شدن در جست‌وجو را تضمین نمی‌کند؛ آن‌ها مسئولیت طراحی و نگهداری شما هستند.

پرسش‌های متداول

چرا پس از فعال‌سازی هنوز ۴۰۴ می‌بینم؟

ممکن است استقرار کامل نشده یا شکست خورده باشد. وضعیت Pages و workflow را بررسی کنید، بعد شاخه و پوشه منتخب را با جای فایل ورودی تطبیق دهید. نام index.html به حروف کوچک حساس است و باید در سطح بالای منبع انتشار باشد.

آیا می‌توانم سایت PHP را همین‌جا اجرا کنم؟

خیر. Pages فایل‌های استاتیک یا خروجی ساخته‌شده را میزبانی می‌کند و زبان سمت سروری مانند PHP یا Python را روی خود سرویس اجرا نمی‌کند. برای قابلیت‌های سمت سرور، میزبان دیگری لازم است.

فرق نشانی سایت شخصی با سایت پروژه چیست؟

سایت شخصی مخزن با نام ویژه username.github.io دارد و در ریشه آن دامنه دیده می‌شود. سایت پروژه زیر همان دامنه، مسیر نام مخزن را هم دارد. همین تفاوت را هنگام نوشتن مسیر تصویر و CSS در نظر بگیرید.

آیا مخزن خصوصی یعنی سایت خصوصی؟

خیر، آن را چنین فرض نکنید. مستندات GitHub هشدار می‌دهد سایت Pages منتشرشده عمومی است، حتی وقتی طرح حساب اجازه استفاده از مخزن خصوصی را می‌دهد. هر فایل و داده‌ای را پیش از انتشار از نظر محرمانگی بازبینی کنید.

جمع‌بندی و گام بعدی

برای یک سایت رزومه استاتیک، مسیر ساده این است: مخزن مناسب، فایل ورودی در بالای منبع، انتخاب Deploy from a branch، مشاهده نتیجه استقرار و آزمون URL عمومی. اگر خطا دیدید، از وضعیت استقرار و جای فایل شروع کنید، سپس سراغ مسیر لینک‌ها و دارایی‌ها بروید. با این ترتیب، ۴۰۴ به جای یک مشکل مبهم، به چند فرضیه قابل‌بررسی تبدیل می‌شود.

فایل‌های سایت رزومه آزمایشی‌تان را در یک مخزن عمومیِ بدون داده محرمانه بگذارید، Pages را از شاخه درست فعال کنید و URL، تصویرها و لینک‌ها را در موبایل بررسی کنید.