Я витратив більше часу, ніж мав би, щоб змусити jekyll-polyglot коректно працювати на GitHub Pages. Проблеми не були концептуально складними, але кожна лишалася невидимою, доки не кусала. Це нотатки, яких я хотів би мати на старті.

GitHub Pages не запустить Polyglot

GitHub Pages підтримує білий список дозволених Jekyll-плагінів. jekyll-polyglot до нього не входить. Якщо додати його в _plugins/-директорію чи Gemfile і запушити, GitHub Pages мовчки збілдить сайт без нього — без помилки, просто сайт без мовної підтримки й кількома поламаними посиланнями.

Виправлення — повністю винести білд з GitHub Pages і використати GitHub Actions для білду й деплою:

# .github/workflows/deploy.yml
name: Deploy Jekyll site
on:
  push:
    branches: [main]
jobs:
  build-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.3'
          bundler-cache: true
      - run: bundle exec jekyll build
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: $
          publish_dir: ./_site

Екшн peaceiris/actions-gh-pages пушить вміст _site/ у гілку gh-pages, яку GitHub Pages віддає як статичний хостинг. Ви втрачаєте простоту push-to-deploy, але отримуєте повну підтримку плагінів.

Несподіванка з переписуванням URL

Основна фіча Polyglot — переписування URL на сторінках недефолтної мови так, щоб /about/ ставав /uk/about/ при білді української версії. Це відбувається автоматично для всіх кореневих відносних href у вашому HTML-виводі.

Несподіванка: це включає й ваш перемикач мов.

Якщо перемикач мов має посилання на кшталт <a href="/uk/about/">English</a>, polyglot перепише його на /uk/about/ на українській сторінці — тобто клік на “English” залишить вас в українській версії. Посилання-на-себе, невидимо.

Виправлення — static_href:

{% static_href %}href="/uk/about/"{% endstatic_href %}

Polyglot бачить цей тег і лишає URL недоторканим незалежно від того, сторінка якої мови білдиться. Це не найкрасивіший Liquid, але правильний інструмент для посилань, які не мають локалізуватися.

data-no-localization не працює для відносних URL

Документація polyglot згадує атрибут data-no-localization, який має запобігати переписуванню URL на конкретних елементах. На практиці це працює для абсолютних URL (https://...), але не для кореневих відносних URL (/path/to/page). Логіка переписування не перевіряє цей атрибут для відносних значень href.

Це не баг у вашій конфігурації. Використовуйте теги static_href для посилань перемикача мов. Не витрачайте пообіддя на налаштування атрибутів data-no-localization.

Gemfile і Git

Багато шаблонів Jekyll-проєктів вносять Gemfile.lock у .gitignore, але взагалі не трекають Gemfile — з припущенням, що Gemfile “очевидна” локальна конфігурація. Це болісно ламається, коли ви додаєте GitHub Actions до білду, бо раннер Actions стартує з нуля без жодного Gemfile.

Переконайтеся, що і Gemfile, і Gemfile.lock закомічені:

git add Gemfile Gemfile.lock
git commit -m "Track Gemfile and lock for CI"

Фіксація Gemfile.lock гарантує, що раннер Actions використовує точно ті самі версії gem, що ви тестували локально, що запобігає режиму відмови “працює на моїй машині, падає в CI”.

Пастка глобального gitignore

Ця зайняла ганебно багато часу на діагностику. Мій глобальний ~/.gitignore_global містив патерн _*, який я додав роками раніше для ігнорування чернеткових директорій з префіксом підкреслення.

Контентні директорії Jekyll усі з префіксом підкреслення: _layouts/, _includes/, _data/, _posts/, _sass/. Усі вони підпадали під глобальний патерн ігнорування. Git їх не трекав.

git status показував чисте робоче дерево. git add _layouts/ мовчки нічого не робив. Сайт білдився локально, бо файли існували на диску; він падав у CI, бо їх ніколи не було закомічено.

Виправлення — явне заперечення в .gitignore проєкту:

# Undo global _* ignore for Jekyll directories
!_layouts/
!_includes/
!_data/
!_posts/
!_sass/
!_config.yml

Альтернативно, приберіть патерн _* з глобального gitignore, якщо він вам насправді не потрібен. Я лишив заперечення на рівні проєкту, бо на інших машинах може бути той самий глобальний патерн.

Ще одне: виключення директорій з локалізації

За замовчуванням polyglot намагатиметься локалізувати все, включно з вашою директорією assets/. Це створює дубльовані копії CSS та зображень під /uk/assets/, що марнотратно і може спричиняти проблеми з кешуванням.

Додайте явні виключення в _config.yml:

exclude_from_localization:
  - assets
  - robots.txt
  - sitemap.xml

Polyglot лишить ці шляхи недоторканими при білді версій недефолтних мов.

Коли всі ці частини на місці, налаштування polyglot справді чисте: один вихідний файл на кожен контент, lang: у front matter, а решту робить плагін. Дістатися цієї точки вимагає лише знання, де розставлені пастки.