Windows проти Linux: чому сторінки Jekyll зникають після публікації на GitHub Pages

Windows проти Linux: чому сторінки Jekyll зникають після публікації на GitHub Pages

Чому сайт на Jekyll працює локально на Windows, але після публікації на GitHub Pages видає помилку 404? Розбираємо збірку Linux, GitHub Actions, плагіни та шляхи до файлів на прикладі WebAnd3D.

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, я б перевіряла все по черзі:

  1. Результат збірки Jekyll. Чи створився потрібний HTML-файл у папці _site?
  2. GitHub Actions. Чи справді збірка завершилася успішно і чи містить артефакт потрібні сторінки?
  3. Налаштування GitHub Pages. Який процес відповідає за публікацію сайту?
  4. Шляхи до файлів і регістр літер. Чи збігаються назви файлів, CSS, зображень і посилань?
  5. Плагіни та залежності. Чи доступні вони в середовищі, де збирається сайт?
  6. Сам опублікований сайт. Чи правильний URL сторінки, чи не залишилася стара версія після розгортання?

Цей список не означає, що причина кожної помилки 404 криється саме в Windows, Linux або GitHub Actions. Це лише спосіб послідовно знайти місце, де результат починає відрізнятися від очікуваного.

Висновок: локально працює — це ще не фінал

Я все ще люблю момент, коли код нарешті працює. Особливо коли не довелося переписувати половину сайту й розмовляти з монітором на підвищених тонах.

Але ця історія нагадала мені: локальна розробка, автоматична збірка Jekyll і публікація на GitHub Pages — це кілька різних етапів. І перевіряти потрібно не лише те, чи сайт працює на моєму комп’ютері, а й те, що саме потрапило до готової версії.

Тепер у мене є перевірка, яка стежить за появою конкретної сторінки моделі. Не штучний інтелект, не магія, не маленький програміст усередині комп’ютера. Просто перевірка файлу. Але іноді саме такі дрібниці рятують від чергового вечора в стилі: «А куди поділися мої сторінки?»

А сайт тим часом продовжує розвиватися: нові STL-моделі, сторінки, завантаження файлів і все більше причин стежити, щоб після git push усе залишалося на своїх місцях.

Бо WebAnd3D — це не лише 3D-моделювання, 3D-друк і веброзробка. Це ще й регулярна практика в мистецтві домовлятися з комп’ютером. Іноді успішно. Іноді — через git push, 404 і чашку кави.

Tags

windows linux jekyll github-pages github-actions веброзробка пошук-помилок статичний-сайт 3d-друк
JK
Про автора

Юлія Карась

Веб розробниця • 3D художниця • AI ентузіастка