در این پست تجربه خودم در راه‌اندازی یک بلاگ فارسی بر پایه Hugo روی صفحات گیتهاب (Github Pages) را می‌نویسم. نوشتن این تجربیات به من کمک می‌کند که اگر در آینده خواستم کاری را تکرار کنم چرخ را دوباره اختراع نکنم. همین نوشته را در سایت فارسی من (که با همین روش ایجاد شده است) در لینک زیر ببیند:
نگارش انگلیسی این نوشته (با کمی تغییر) را در لینک زیر می‌توانید ببینید:
در سایت انگلیسی من نمی‌توان فارسی نوشت چون قالب سایت از راست-به-چپ پشتیبانی نمی‌کند. سایت اصلی من بر روی AWS قرار دارد که متاسفانه استفاده از این سرویس‌ها در ایران امکانپذیر نیست. اما صفحات گیتهاب علاوه بر مجانی بودن دیگر شامل تحریم نیستند. گیتهاب پس از دو سال سر و کله زدن توانسته مجوز مربوطه را بگیرد.
صفحات گیتهاب به صورت native از Jekyll پشتیبانی می‌کنند ولی کار با Hugo برای من راحت‌تر است. تقریباً تمام سایتهای من توسط Hugo تولید شده‌اند. اکثر این static website generator ها (مولّد سایت استاتیک؟) روش کاری یکسانی دارند. شما مطالب را با فرمت markdown می‌نویسید و بقیه کار را به آنها می‌سپارید.
لزومی ندارد حتماً از هوگو و یا جِکیل استفاده کنید، هر مولّدی که با آن راحت‌تر هستید را انتخاب کنید. به احتمال زیاد راهنمای استفاده از آن برای صفحات گیتهاب وجود دارد. خوشبختانه دیگر نیازی به اجرای دستی بسیاری از مراحل نیست و Github actions به کمک ما می‌آیند.
برای این پست شما باید یکسری موارد را بدانید:
بر روی گیتهاب می‌توانیم سه نوع سایت مختلف داشته باشیم:
با استفاده از سایتهای پروژه شما می‌توانید تعداد نامحدود سایت در صفحات گیتهاب داشته باشید.
من از سایت فارسی خودم برای مثال استفاده می‌کنم که یک سایت پروژه است:
قالب سایت من قابلیت راست-به-چپ ندارد. آن را خودم از 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 قالب را کپی و دستکاری می‌کردم (که البته آخر دنیا هم نبود). تا قبل از نوشتن این مقاله از همین روش استفاده کرده بودم.
اکنون وقت ایجاد Github action است. برای تولید یک سایت توسط Hugo از راهنمای زیر استفاده کردم (که اشتباهات کوچکی هم داشت):
نیازی به دستکاری این فایل نبود و عیناً آن را در مخزن سایت کپی کردم.
به طور خلاصه، هر کامیت در شاخه 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 های زیر است:
سپس یک رکورد CNAME با host با مقدار زیر (نقطه اضافی در آخر مقدار را فراموش نکنید):
parsiya.github.io.
نکته امنیتی: از wildcard در این رکورد CNAME استفاده نکنید. مثلاً ننویسید:
*.whatever.com
اگر چنین تنظیمی داشته باشید هر اکانت گیتهاب می‌تواند یک سایت را در subdomain های سایت شما هاست (همون host که نمی‌دونم فارسیش چی میشه) کُنَد. انگلیسی این اخطار را در این صفحه بخوانید.
کار بعدی رفتن داخل تنظیمات صفحه در گیتهاب بود. در بخش Custom Domain دامنه را وارد کردم.
این کار یک کامیت جدید تولید می‌کند. این کامیت یک فایل به نام CNAME را به مخزن اضافه می‌کند. مقدار این فایل همان دامنه‌ای است که در بخش قبل استفاده کردیم. صفحات گیتهاب از این فایل برای تشخیص دامنه شخصی استفاده می‌کند.
اگر راهنمای Hugo برای صفحات گیتهاب را دنبال کرده باشید یک فایل مشابه در دایرکتوری static مخزن دارید. واقعاً نمی‌دانم هر دوی این فایلها لازم هستند و یا خیر. ولی وقتی سایت کار می‌کند دستکاری آن فایده‌ای ندارد.
یک مشکل بزرگ عدم پشتیبانی Visual Studio Code از راست-به-چپ است. تقریباً همه نوشته‌های من در این ادیتور است. این کار سرعت من را پایین آورد چون مجبور شدم از ادیتور Notepad++ استفاده کنم. در VS Code من تعداد زیادی snippet و shortcut دارم که سرعتم را زیاد می‌کنند.
مشکل بعدی انتخاب محدود قالب است. قالبهایی که از راست-به-چپ پشتیبانی می‌کنند کم هستند. علاقه زیادی به PaperMod ندارم (قالب خوبی است ولی من دوست ندارم) اما از بقیه بهتر بود.
بزرگترین مشکل هم نوشتن به فارسی است که زبانم (دستم؟) نمی‌چرخد. همین معادلسازی یا نیم‌فاصله (ctrl+shift+2) پدر من را درآورده اند ?.
این بخشی است که من در تقریباً همه مقاله‌هایم می‌نویسم.
یادگرفتم که اگر خواستم بلاگ فارسی بر پایه Hugo در صفحه گیتهاب (و با دامنه مخصوص) داشته باشم چکار کنم.
