اسناد ساده تر با صفحات GitHub

صفحات GitHub به شما امکان می دهد محتوا را دقیقاً به همان روشی که کد را مدیریت می کنید مدیریت کنید و از شاخه های توسعه محتوا به سمت اصلی برای انتشار محتوای جدید هدایت کنید. این یک راه عالی برای اطمینان از اینکه کد و اسناد در کنار هم تحویل داده می شوند است.

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

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

با توجه به اینکه مستندات جزء کلیدی فرآیند CI/CD (ادغام پیوسته و تحویل مستمر) است، ما به یک روش انتشار نیاز داریم که بتوان آن را در ساخت‌هایمان ادغام کرد. . بنابراین، خوب است ببینید که GitHub یک پلت فرم انتشار وب را در مخازن خود ایجاد کرده است.

تنظیم صفحات GitHub

در صفحات GitHub چیزهای زیادی برای لایک کردن وجود دارد. می توانید مجموعه ای از صفحات را به یک مخزن پروژه گره بزنید و مجموعه ای برای یک کاربر یا یک سازمان داشته باشید. محتوا در مخزن ذخیره می‌شود و به یک نشانی اینترنتی با میزبانی GitHub تحویل داده می‌شود یا به یک دامنه سفارشی. می‌توانید دقیقاً به همان روشی که کد را مدیریت می‌کنید، محتوا را مدیریت کنید، از شاخه‌های توسعه محتوا به سمت اصلی برای انتشار محتوای جدید فشار دهید. پشتیبانی برای تعریف چه شاخه‌هایی برای انتشار از استفاده می‌شوند، و همچنین اقداماتی برای خودکارسازی انتشار.

شما حتی نیازی به استفاده از HTML ندارید. صفحات GitHub را می توان با گویش Markdown خود GitHub ایجاد کرد و قالب بندی اولیه را ساده می کند. این کار شروع سریع و آسان می کند—شما می توانید صفحه اول خود را بدون ترک سایت اضافه کنید. تنها کاری که برای ایجاد یک سایت شخصی باید انجام دهید این است که با استفاده از نام کاربری GitHub خود یک مخزن جدید به حساب خود اضافه کنید و آن را username.github.io نامید. برای مقداردهی اولیه سایت، ابتدا یک صفحه فهرست به صورت HTML یا Markdown ایجاد کنید و آن را به مخزن جدید فشار دهید. برای مشاهده سایت خود به نشانی اینترنتی که نام مخزن است بروید.

اگرچه URL پیش فرض به اندازه کافی خوب کار می کند، GitHub به شما امکان می دهد با یک دامنه سفارشی به سایت خود دسترسی داشته باشید. اگر یک URL خاص می خواهید، یک CNAME تنظیم شده در DNS شما به خوبی کار می کند. اگر ترجیح می دهید نام دامنه را URL خود قرار دهید، GitHub لیستی از آدرس های IP را ارائه می دهد که باید برای سایت پیکربندی شوند. هنگامی که DNS خود را تنظیم کردید، GitHub تنظیمات را قبل از فعال کردن دامنه شما تأیید می کند.

می توانید سایت خود را برای استفاده از TLS (امنیت لایه حمل و نقل) از طریق پشتیبانی داخلی برای گواهینامه های رایگان Let’s Encrypt پیکربندی کنید. . GitHub گواهی ها را برای شما مدیریت می کند و به طور خودکار به روز می شود. فرآیند صدور و نصب گواهی تنها چند دقیقه طول می‌کشد، و پس از برقراری آن، می‌توانید دسترسی را قفل کنید تا فقط اتصالات امن مجاز باشد.

استفاده از صفحات GitHub با مولدهای سایت استاتیک

صفحات GitHub با پشتیبانی مستقیم از جکیل مبتنی بر روبی، شامل مجموعه ای از تم های میزبانی شده توسط GitHub. یکی از جایگزین‌هایی که به‌ویژه محبوب شده است Hugo است، ابزاری برای ساخت و مدیریت سایت که در Go نوشته شده است و از طریق بسیاری از نرم‌افزارهای رایج در دسترس است. خدمات توزیع بسته از آنجایی که هر بار که تغییری ایجاد می‌کنید، سایت‌های ثابت نیاز به بازسازی دارند، یافتن سایتی که به سرعت هوگو باشد خوب است، زیرا بازسازی یک سایت برای انتشار چند ثانیه طول می‌کشد.

دو راه برای استفاده از Hugo با صفحات GitHub وجود دارد. ساده ترین گزینه این است که قبل از انتقال محتوا به مخزن GitHub خود، یک کپی محلی نصب کنید و محتوا را به صورت محلی بسازید. اگر از ویندوز استفاده می کنید، می توانید به سرعت Hugo را با استفاده از مدیریت بسته Chocolatey راه اندازی کنید. Chocolatey CLI از طریق ترمینال ویندوز قابل دسترسی است، جایی که Hugo را نصب و پیکربندی می کند، مسیر مناسب را تنظیم می کند و مطمئن می شود که آخرین نسخه را دارید. پس از نصب، ترمینال ویندوز را ببندید و دوباره باز کنید تا یک مسیر به روز شده بارگیری شود و نصب Hugo خود را آزمایش کنید.

استفاده از Hugo با صفحات GitHub

Hugo یک ابزار خط فرمان است، که استفاده از آن را با ویرایشگری مانند Visual Studio Code ایده‌آل می‌کند. می‌توانید از کد برای ویرایش فایل‌های پیکربندی Hugo و ایجاد محتوای Markdown استفاده کنید، با یک پایانه باز برای اجرای دستورات Hugo در صورت نیاز. توسعه پذیری کد در اینجا نیز مطرح می شود، زیرا می تواند از ادغام GitHub برای مدیریت آپلودها در مخزن صفحات شما و پشتیبانی از Markdown برای کاهش خطر خطا استفاده کند. حتی برنامه های افزودنی مخصوص Hugo برای کمک به ساخت و مدیریت محتوای سایت وجود دارد.

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

می‌توانید عملکرد اصلی سایت را با استفاده از سرور داخلی آزمایش کنید. این یک ابزار مفید برای ادامه کار است. هنگامی که هر محتوای جدیدی را ذخیره می کنید، سرور محلی مجموعه به روز شده ای از صفحات را برای آزمایش آماده می کند. سرور محلی دستورات Markdown و Hugo را به HTML و JavaScript کامپایل نمی کند. یک مترجم محلی را اجرا می کند و محتوا را در لحظه نمایش می دهد. نتیجه راهی برای پیش نمایش و آزمایش صفحات در حین ساختن آنها است.

هنگامی که آماده انتشار سایت خود شدید، سرور محلی را متوقف کرده و Hugo را برای تبدیل سایت خود به HTML اجرا کنید. سپس می توانید HTML حاصل را به GitHub فشار دهید، جایی که برای دیدن کاربران آماده خواهد بود. اگر پوشه‌هایی وجود دارد که نمی‌خواهید به GitHub فشار دهید (مثلاً محتوای Markdown شما) به سادگی یک فایل .gitignore را به آنها اضافه کنید و کلاینت git شما آنها را به مخزن شما منتقل نمی‌کند.

معمولا Hugo قابل توسعه است و از کدهای کوتاه برای حذف HTML و جاوا اسکریپت از پیش تعریف شده استفاده می کند. بسیاری از تم ها کدهای کوتاه خود را اضافه می کنند، به ویژه تم هایی که برای انواع خاصی از محتوا طراحی شده اند یا از جاوا اسکریپت برای دسترسی به API های خارجی استفاده می کنند. به عنوان مثال، از آنجایی که برای کار با Markdown طراحی شده است، هیچ پشتیبانی مستقیمی از HTML وجود ندارد. با استفاده از ابزارهای قالب مبتنی بر Go آن، می‌توانید به سرعت یک کد کوتاه سفارشی که می تواند هر محتوای HTML را که می خواهید در یک صفحه قرار دهید بپیچد.

انتشار محتوا با استفاده از GitHub Actions

استفاده از ابزار git برای ارسال محتوای Hugo کامپایل شده به اندازه کافی خوب کار می کند، اما برای سایت هایی که نیاز به اجرای چندین کاربر با چندین شاخه توسعه دارند، توصیه نمی شود. تیم توسعه Hugo مجموعه ای از اقدامات GitHub را ارائه می دهد که می تواند به انتشار خودکار کمک کند کاربران شاخه های خود را نگه می دارند و از درخواست های کششی برای به روز رسانی شاخه اصلی استفاده می کنند. هنگامی که هر درخواست کششی تأیید شد، Action با استفاده از نمونه Hugo میزبان GitHub برای کامپایل صفحات و ذخیره محتوای حاصل در یک شاخه جدید gh-pages اجرا می‌شود.

می‌توانید صفحات GitHub را برای ارائه محتوا از شاخه Actions-powered پیکربندی کنید تا بتوانید یک گردش کار مناسب برای تیم محتوای خود ایجاد کنید. همین فرآیند برای صفحات کاربر، سازمان و پروژه کار می کند.

GitHub ممکن است اولین انتخاب شما به عنوان میزبان وب نباشد، اما یک گزینه به‌طور شگفت‌آور انعطاف‌پذیر است. قادر به پشتیبانی از تولید محتوای سمت سرور نیست، اما استفاده از جاوا اسکریپت و تولیدکننده‌های سایت استاتیک به این معنی است که می‌تواند محتوای تعاملی را در حالی که از گردش کار ایجاد محتوای مبتنی بر git پشتیبانی می‌کند، ارائه دهد. این رویکرد به شما امکان می‌دهد آن را با فرآیندهای توسعه نرم‌افزار مشابه ادغام کنید و اطمینان حاصل کنید که کد و اسناد در کنار هم ارائه می‌شوند.