توسعه و میزبانی سایت روی صفحات گیت‌هاب

در این پست تجربه خودم در راه‌اندازی یک بلاگ فارسی بر پایه Hugo روی صفحات گیت‌هاب (Github Pages) را می‌نویسم. نوشتن این تجربیات به من کمک می‌کند که اگر در آینده خواستم کاری را تکرار کنم چرخ را دوباره اختراع نکنم. همین نوشته را در سایت فارسی من (که با همین روش ایجاد شده است) در لینک زیر ببیند:https://parsiya.github.io/parsiya.fa/post/github-actions-farsi-site/نگارش انگلیسی این نوشته (با کمی تغییر) را در لینک زیر می‎‌توانید ببینید:https://parsiya.net/blog/2021-02-17-automagically-deploying-websites-with-custom-domains-to-github-pages/چرا گیت‌هاب؟در سایت انگلیسی من نمی‌توان فارسی نوشت چون قالب سایت از راست-به-چپ پشتیبانی نمی‌کند. سایت اصلی من بر روی AWS قرار دارد که متاسفانه استفاده از این سرویس‌ها در ایران امکانپذیر نیست. اما صفحات گیت‌هاب علاوه بر مجانی بودن دیگر شامل تحریم نیستند. گیت‌هاب پس از دو سال سر و کله زدن توانسته مجوز مربوطه را بگیرد.چرا Hugo؟ صفحات گیت‌هاب به صورت native از Jekyll پشتیبانی می‌کنند ولی کار با Hugo برای من راحت‌تر است. تقریباً تمام سایتهای من توسط Hugo تولید شده‌اند. اکثر این static website generator ها (مولّد سایت استاتیک؟) روش کاری یکسانی دارند. شما مطالب را با فرمت markdown می‌نویسید و بقیه کار را به آنها می‌سپارید.لزومی ندارد حتماً از هوگو و یا جِکیل استفاده کنید، هر مولّدی که با آن راحت‌تر هستید را انتخاب کنید. به احتمال زیاد راهنمای استفاده از آن برای صفحات گیت‌هاب وجود دارد. خوشبختانه دیگر نیازی به اجرای دستی بسیاری از مراحل نیست و Github actions به کمک ما می‌آیند.روش استفاده کل سایت در یک repository (مخزن؟) گیت در گیت‌هاب ذخیره می‌شود.مطالب را به فرمت markdown می‌نویسید و در یک یا چند کامیت به مخزن اضافه می‌کنید.پس از هر کامیت یک Github action سایت را تولید می‌کند.سایت تولید شده در یک branch (شاخه؟) مجزا ذخیره می‌شود.گیت‌هاب این شاخه را به عنوان یک سایت، serve می‌کند (فارسیش چی میشه؟).دانش پیشینبرای این پست شما باید یکسری موارد را بدانید:آشنایی با Hugo (اگر از مولّد سایت دیگری استفاده می‌کنید می‌توانید بخشهای مربوط به Hugo را سرسری رد شوید).آشنایی ابتدایی با گیت. در حد اینکه کامیت و شاخه چه هستند.انواع صفحات گیت‌هاببر روی گیت‌هاب می‌توانیم سه نوع سایت مختلف داشته باشیم:سایت کاربر یا user site: هر نام کاربری می‌تواند یک سایت در آدرس username.github.io داشته باشد.سایت سازمان یا organization site: مشابه صفحه کاربر است. مثلاٌ https://microsoft.github.io.سایت پروژه یا project site: هر پروژه می‌تواند یک سایت مجزا داشته باشد. آدرس سایت پروژه وابسته به نام کاربری یا سازمانی است که صاحب اکانت است.با استفاده از سایت‎های پروژه شما می‌توانید تعداد نامحدود سایت در صفحات گیت‌هاب داشته باشید.من از سایت فارسی خودم برای مثال استفاده می‌کنم که یک سایت پروژه است:آدرس سایت: https://parsiya.github.io/parsiya.faآدرس مخزن سایت: https://github.com/parsiya/parsiya.faقالب با متن راست-به-چپقالب سایت من قابلیت راست-به-چپ ندارد. آن را خودم از Octopress به Hugo منتقل کرده‌ام و از css چیز زیادی نمی‌دانم. بنابراین تصمیم گرفتم از قالب دیگری استفاده کنم. بعد از چند انتخاب به قالب hugo-PaperMod رسیدم. Hugo از زبانهای مختلف در سایت پشتیبانی می‌کند. معمولاً این برای انتشار نسخه‌های یک صفحه (یا سایت) به چند زبان استفاده می‌شود. شما یک صفحه را به انگلیسی و فارسی می‌نویسید و Hugo بقیه کار را انجام می‌دهد.من تنها می‌خواهم به فارسی بنویسم پس نیازی به استفاده از چند زبان ندارم. این موارد را به config.yml سایتم اضافه کردم:languageCode: fa defaultContentLanguage: fa languages: fa: languagedirection: rtl weight: 1استفاده از فونت وزیرکار دیگر استفاده از فونت فارسی وزیر بود. ویرگول هم از این فونت استفاده می‌کند. خوشبختانه این فونت یک مجوز باز برای استفاده دارد.مرحله اول دانلود فونت وزیر و قراردادن آن در دایرکتوری static سایت بود. در Hugo هر چیزی که در static باشد عیناً به root خود سایت اضافه می‌شود. فونت وزیر دو بخش دارد یکی خود فایل‌های فونت و دیگر css. اینها را در دایرکتوری‎‌های جداگانه قرار دادم (این کار لزومی ندارد ولی خوشگل‌تر است).مرحله دوم اضافه کردن css فونت به قالب بود. در Hugo برای شخصی‌سازی قالب نیازی به دستکاری مستقیم آن نیست. برای اضافه کردن css باید فایل مربوط به بخش head هر صفحه قالب را دستکاری می‌کردم. در این قالب برای دستکاری این بخش می‌توان از فایل extend-head.html استفاده کرد.یک کپی از این فایل را در خود سایت ایجاد کردم که در https://github.com/parsiya/parsiya.fa/blob/main/layouts/partials/extend_head.html است. هنگام تولید سایت محتویات این فایل مستقیما به تگ head هر صفحه اضافه می‌شود.استفاده از چنین فایل‌هایی یکی از روش‌های خوب قالب‌ها برای شخصی‌سازی است. اگر چنین فایلی نبود باید کل layout/partials/head.html قالب را کپی و دستکاری می‌کردم (که البته آخر دنیا هم نبود). تا قبل از نوشتن این مقاله از همین روش استفاده کرده بودم.ایجاد workflowاکنون وقت ایجاد Github action است. برای تولید یک سایت توسط Hugo از راهنمای زیر استفاده کردم (که اشتباهات کوچکی هم داشت):https://gohugo.io/hosting-and-deployment/hosting-on-github/#build-hugo-with-github-actionنیازی به دستکاری این فایل نبود و عیناً آن را در مخزن سایت کپی کردم.https://github.com/parsiya/parsiya.fa/blob/main/.github/workflows/gh-pages.ymlبه طور خلاصه، هر کامیت در شاخه main باعث شروع action می‌شود و سایت را تولید و سپس در شاخه gh-pages ذخیره می‌کند.یک نمونه از اجرای این action را می‌توانید در این لینک ببینید. با push کردن کامیتی که حاوی پست جدید (همین پست در بلاگ فارسی است، این action آن را منتشر کرده). روی هر کدام از مراحل مانند Setup Hugo یا Deploy کلیک کنید تا جزئیات را ببینید.تنظیمات صفحه گیت‌هابداخل هر مخزن در بخش settings/pages می‌توان شاخه‌ای که دارای صفحات سایت است را مشخص کرد. این کار را باید بعد از ایجاد شاخه در مخزن انجام دهید چون شاخه‌ای که وجود ندارد را نمی‌توانید انتخاب کنید.تنظیمات صفحه گیت‌هاب برای سایت مندامنه شخصیکار من در اینجا تمام شد امّا هر کدام از این سایتها می‌توانند دامنه مخصوص به خود را داشته باشند. مثلاً یکی از سایتهای من به اسم begbounty.com یک سایت پروژه در مخزن https://github.com/parsiya/begbounty.com است. راهنماهای زیادی برای استفاده از دامنه شخصی برای سایتهای کاربران و سازمان‌ها بود ولی تنظیمات برای سایتهای پروژه نتایج جستجوی زیادی نداشت.برای این کار باید به تنظیمات DNS دامنه خود دسترسی داشته باشید. چند تا از دامنه‌های من در namecheap هستند و این قابلیت را دارند. همه رکوردهای DNS دامنه خود را پاک کردم.اول چهار A Record اضافه کردم. host این رکوردها @ و مقدار آنها IP های زیر است:185.199.108.153185.199.109.153185.199.110.153185.199.111.153سپس یک رکورد CNAME با host با مقدار زیر (نقطه اضافی در آخر مقدار را فراموش نکنید):parsiya.github.io.نکته امنیتی: از wildcard در این رکورد CNAME استفاده نکنید. مثلاً ننویسید:*.whatever.comاگر چنین تنظیمی داشته باشید هر اکانت گیت‌هاب می‌تواند یک سایت را در subdomain های سایت شما هاست (همون host که نمی‌دونم فارسیش چی میشه) کُنَد. انگلیسی این اخطار را در این صفحه بخوانید.کار بعدی رفتن داخل تنظیمات صفحه در گیت‌هاب بود. در بخش Custom Domain دامنه را وارد کردم.تنظیمات صفحه گیت‌هاب begbounty.comاین کار یک کامیت جدید تولید می‌کند. این کامیت یک فایل به نام CNAME را به مخزن اضافه می‌کند. مقدار این فایل همان دامنه‌ای است که در بخش قبل استفاده کردیم. صفحات گیت‌هاب از این فایل برای تشخیص دامنه شخصی استفاده می‌کند.اگر راهنمای Hugo برای صفحات گیت‌هاب را دنبال کرده باشید یک فایل مشابه در دایرکتوری static مخزن دارید. واقعاً نمی‌دانم هر دوی این فایلها لازم هستند و یا خیر. ولی وقتی سایت کار می‌‎‌کند دستکاری آن فایده‌ای ندارد.مشکلاتیک مشکل بزرگ عدم پشتیبانی Visual Studio Code از راست-به-چپ است. تقریباً همه نوشته‌های من در این ادیتور است. این کار سرعت من را پایین آورد چون مجبور شدم از ادیتور Notepad++ استفاده کنم. در VS Code من تعداد زیادی snippet و shortcut دارم که سرعتم را زیاد می‌کنند.مشکل بعدی انتخاب محدود قالب است. قالبهایی که از راست-به-چپ پشتیبانی می‌کنند کم هستند. علاقه زیادی به PaperMod ندارم (قالب خوبی است ولی من دوست ندارم) اما از بقیه بهتر بود.بزرگترین مشکل هم نوشتن به فارسی است که زبانم (دستم؟) نمی‌چرخد. همین معادلسازی یا نیم‌فاصله (ctrl+shift+2) پدر من را درآورده اند ?.چی یاد گرفتم؟این بخشی است که من در تقریباً همه مقاله‌هایم می‌نویسم.یادگرفتم که اگر خواستم بلاگ فارسی بر پایه Hugo در صفحه گیت‌هاب (و با دامنه مخصوص) داشته باشم چکار کنم.