Windows проти Linux: чому сторінки Jekyll зникають після публікації на GitHub Pages
Мій сайт WebAnd3D, як ви вже знаєте, знаходиться на GitHub Pages. А я працюю на Windows.
Локально сайт працює. Є в мене сторінки, які автоматично генеруються за допомогою плагіна Jekyll. Тобто сайт бере з потрібних папок зображення, читає їхні назви, витягує дані з файлів і за заданим шаблоном створює готові сторінки моделей для 3D-друку.
Наприклад, сторінки STL-моделей. Картинки, опис, назва, налаштування друку — усе збирається докупи, і мені не потрібно вручну створювати окремий HTML-файл для кожної моделі.
І ось знаєте це відчуття, коли локально сайт працює ідеально? Усі сторінки на місці, CSS завантажується, кнопки натискаються. Ти задоволена собою, робиш git push і йдеш перевіряти результат.
А там дуля.
404 — сторінку не знайдено.
І ти така: «Блін, ти дурне! Ей, де мої сторінки? Вони ж працювали на локалці!»
На GitHub Actions уже теж не Pending і не In progress. Усе зелененьке, збірка сайту успішна, публікація завершена. Хто працює з GitHub, той знає: зелена галочка — це приємно, але іноді вона означає лише те, що комп’ютер успішно зробив не зовсім те, на що ти сподівалася.
Windows і Linux: однаковий код, різні правила гри
Перша думка — щось зламалося під час публікації сайту на GitHub Pages. Але чому? Локально ж усе працює!
Тут варто пам’ятати одну річ: локальна розробка на Windows і збірка сайту на Linux у GitHub Actions — це не одне й те саме середовище.
У мене сайт збирається локально на Windows, а GitHub Actions запускає процес збірки в середовищі Linux. І між ними є відмінності, які легко пропустити, коли перевіряєш лише локальну версію сайту.
Наприклад, регістр літер у назвах файлів.
Для Windows назви Main.css і main.css зазвичай означають той самий файл. А Linux розрізняє великі й малі літери. Тому якщо в HTML вказано Main.css, а файл насправді називається main.css, локально все може виглядати чудово, а після публікації CSS раптом перестане завантажуватися.
І це ще відносно простий випадок. Коли йдеться про автоматичну генерацію сторінок, є й інші місця, де можна шукати проблему.
Коли Jekyll генерує сторінки автоматично
Мій сайт WebAnd3D використовує Jekyll — генератор статичних сайтів. Він перетворює шаблони, дані та інші файли на готові HTML-сторінки.
Для сторінок моделей 3D-друку я використовую плагін jekyll-datapage-generator. Він допомагає створювати сторінки за даними та шаблонами, а не писати кожну вручну.
Уявіть: додала модель, підготувала зображення й дані — і сайт має згенерувати сторінку на кшталт:
/models/automotive-parts/chery-tiggo/
Саме такі сторінки особливо цікаво перевіряти після публікації. Адже недостатньо, щоб сам сайт успішно зібрався. Потрібно ще переконатися, що потрібні сторінки справді потрапили до результату збірки.
І тут є важливий нюанс: локально працює jekyll serve — ще не означає, що готовий сайт зібрався так само, як у production-середовищі.
Тому я почала перевіряти не лише те, чи відкривається сторінка в браузері, а й те, чи створюється відповідний HTML-файл після збірки.
GitHub Actions: зелена галочка — це ще не вся історія
Для автоматичної збірки та публікації я налаштувала GitHub Actions. Він запускає Jekyll у Linux, збирає сайт і передає готові файли на GitHub Pages.
У робочому процесі я додала окрему перевірку для сторінки Chery Tiggo:
if [ ! -f "_site/models/automotive-parts/chery-tiggo/index.html" ]; then
echo "ERROR: Chery Tiggo page was not generated"
exit 1
fi
echo "Chery Tiggo page generated successfully"
Тепер збірка перевіряє, чи існує файл сторінки після генерації. Якщо його немає, процес має завершитися з помилкою, а не просто показати зелену галочку.
Це не гарантує, що сторінка бездоганно відкриватиметься в браузері, але допомагає відловити конкретну проблему ще на етапі збірки.
Під час розслідування я також побачила в GitHub Actions два окремі процеси: мій Build and deploy WebAnd3D та pages build and deployment. Сам факт їхньої наявності ще не доводить, що вони конфліктували, але це стало приводом перевірити налаштування публікації GitHub Pages і переконатися, що сайт розгортається саме тим способом, який я налаштувала.
Бо коли маєш кілька можливих місць, де щось пішло не так, краще перевіряти факти, а не призначати винним перший-ліпший рядок коду.
А що з Gemfile.lock і залежностями?
Є ще один момент у розробці сайтів на Jekyll — залежності Ruby та Bundler.
Файл Gemfile описує потрібні бібліотеки й плагіни, а Gemfile.lock фіксує конкретні версії залежностей. Це допомагає зробити збірку відтворюваною, але коли сайт розробляється на Windows, а збирається на Linux, важливо враховувати обидві платформи.
У моєму випадку я додала Linux як платформу для Bundler:
bundle lock --add-platform x86_64-linux
Ця команда оновлює Gemfile.lock, щоб Bundler враховував залежності для Linux. Вона не виправляє автоматично будь-яку помилку збірки, але допомагає уникнути проблем, пов’язаних із платформозалежними залежностями.
А ще варто пам’ятати, що не кожен плагін Jekyll доступний у стандартному процесі збірки GitHub Pages. Якщо сайт використовує сторонні плагіни, може знадобитися власна збірка через GitHub Actions. Саме тому важливо перевіряти не лише код, а й спосіб публікації сайту.
Що я перевірятиму наступного разу
Коли локальна версія сайту працює, а після публікації на GitHub Pages з’являється помилка 404, я б перевіряла все по черзі:
- Результат збірки Jekyll. Чи створився потрібний HTML-файл у папці
_site? - GitHub Actions. Чи справді збірка завершилася успішно і чи містить артефакт потрібні сторінки?
- Налаштування GitHub Pages. Який процес відповідає за публікацію сайту?
- Шляхи до файлів і регістр літер. Чи збігаються назви файлів, CSS, зображень і посилань?
- Плагіни та залежності. Чи доступні вони в середовищі, де збирається сайт?
- Сам опублікований сайт. Чи правильний URL сторінки, чи не залишилася стара версія після розгортання?
Цей список не означає, що причина кожної помилки 404 криється саме в Windows, Linux або GitHub Actions. Це лише спосіб послідовно знайти місце, де результат починає відрізнятися від очікуваного.
Висновок: локально працює — це ще не фінал
Я все ще люблю момент, коли код нарешті працює. Особливо коли не довелося переписувати половину сайту й розмовляти з монітором на підвищених тонах.
Але ця історія нагадала мені: локальна розробка, автоматична збірка Jekyll і публікація на GitHub Pages — це кілька різних етапів. І перевіряти потрібно не лише те, чи сайт працює на моєму комп’ютері, а й те, що саме потрапило до готової версії.
Тепер у мене є перевірка, яка стежить за появою конкретної сторінки моделі. Не штучний інтелект, не магія, не маленький програміст усередині комп’ютера. Просто перевірка файлу. Але іноді саме такі дрібниці рятують від чергового вечора в стилі: «А куди поділися мої сторінки?»
А сайт тим часом продовжує розвиватися: нові STL-моделі, сторінки, завантаження файлів і все більше причин стежити, щоб після git push усе залишалося на своїх місцях.
Бо WebAnd3D — це не лише 3D-моделювання, 3D-друк і веброзробка. Це ще й регулярна практика в мистецтві домовлятися з комп’ютером. Іноді успішно. Іноді — через git push, 404 і чашку кави.