Налаштування та кастомізація теми Jekyll: стилі, шаблони, плагіни

Jekyll тема: де ламається збірка та верстка

Готова тема майже завжди зібрана під конкретну версію генератора та набір плагінів, тому вже перший bundle exec jekyll build після встановлення часто падає через несумісність залежностей: тема тягне плагін, який вимагає іншої мажорної гілки, а Gemfile вже зафіксований під чужий набір.

Симптом — збірка сайту проходить локально, але розвалюється на CI, бо там підтягується свіжа версія gem-а.

Другий клас збоїв — конфлікт шаблонів. Тема приносить свої _layouts та _includes, і при додаванні власних сторінок Liquid-успадкування ламається: layout: default з теми перекриває ваш, а include підтягує чужий partial.

Верстка при цьому роз'їжджається не одразу — спочатку зникає обгортка, потім з'їжджає сітка на внутрішніх сторінках.

Третє джерело — плагіни. Частина тем розрахована на збірку через GitHub Pages з обмеженим whitelist, і будь-який плагін поза списком мовчки ігнорується: Sass не компілюється, пагінація не з'являється, а вивід залишається порожнім без явної помилки.

Окремо спливає верстка на адаптиві: тема версталася під фіксовану ширину контенту, і довгі таблиці або код-блоки вилазять за в'юпорт. Плюс версії ассетів не скидаються, і браузер тримає старий CSS після правок.

Розбираємо, як кожен із цих збоїв закривається — від фіксації залежностей до перевизначення шаблонів без правки файлів теми.

Що дає налаштована тема: швидкість і стабільність

Складання Jekyll-сайту деградує непомітно: спочатку 8 секунд, потім 40, потім хвилини на кожну зміну. Причина майже завжди одна — тема тягне за собою весь набір плагінів і шаблонних залежностей, навіть якщо конкретна сторінка використовує десяту частину.

Інкрементальне перескладання перестає допомагати, бо будь-яка правка в загальному макеті інвалідує весь кеш, і ви чекаєте повний цикл заради одного рядка в тексті.

Кастомізація теми вирішує це на рівні структури, а не косметики. Ми розносимо макети за призначенням, виносимо важкі обчислення з шаблонів у підключувані дані, вимикаємо невикористовувані плагіни й фіксуємо версії залежностей.

Час складання падає передбачувано — типовий проєкт прискорюється в рази, а гаряче перескладання повертається до секунд, бо перестає залежати від усього дерева шаблонів.

Другий ефект — зникає цілий клас помилок виводу. Кривий Liquid-фільтр, неекранований символ у заголовку, бите посилання в навігації, дубльовані метатеги — усе це проявляється не на складанні, а на живому сайті, і ловиться вже за скаргами.

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

Окремо — стабільність між середовищами. Локальна машина, тестовий стенд і продакшен складають один і той самий результат, бо версії зафіксовані, а конфігурація різниться лише перевизначенням параметрів.

Це знімає класичне «у мене працює, а на сервері ні» і робить відкат до попереднього стану рутинною операцією, а не розбором причин.

У сумі налаштована тема — це передбачуваний конвеєр публікації: правка доїжджає до сайту за секунди, вивід однаковий усюди, а помилки видно на етапі складання, а не на проді. Далі розберемо, з чого складається таке налаштування.

Підходи до кастомізації: порівняння варіантів

Кастомізація Jekyll-теми майже завжди зводиться до одного питання: що робити, коли потрібно відійти від авторського оформлення. Є три принципово різні способи — правити вихідні коди теми напряму, перевизначати окремі файли поверх неї або будувати власний шар оформлення.

Вибір визначає, що станеться при наступному оновленні теми і скільки часу піде на підтримку через півроку.

Правка вихідних кодів дає швидкий результат і повний контроль, але кожне оновлення теми перетворюється на ручне злиття. Перевизначення — компроміс: ми кладемо свої версії файлів у проєкт, і Jekyll віддає пріоритет їм, а решту бере з теми.

Це працює для стилів, частини шаблонів і конфігурації, але не рятує, якщо змінюється структура даних, на яку спирається тема.

Власний шар — найстійкіший шлях для проєктів, які живуть роками. Тема залишається незмінною залежністю, а весь наш код лежить окремо: свої макети, свої стилі, свої підключувані блоки.

Оновлення теми тоді не ламає оформлення, а додавання нового розділу не вимагає лізти в чужі файли. Розбираємо, як вибрати варіант під ваш випадок і що врахувати при перенесенні.

Етапи налаштування та кастомізації теми

Роботу починаємо з аудиту: дивимося, що в темі вже є, а що доведеться переписувати. Перевіряємо структуру каталогів, набір шаблонів, підключені плагіни та те, як збирається сайт на поточній гілці Jekyll.

На виході — карта теми: які файли відповідають за виведення, де дублюється розмітка, які залежності тягнуть зайву вагу.

1. Аудит теми. Розбираємо вихідні коди, колекції, layouts та includes, фіксуємо точки кастомізації та ризики: жорстко прописані шляхи, розрослий _config.yml, плагіни без підтримки. Звіряємо поведінку з тим, що заявлено в задачі.
2. Проєктування структури. Вирішуємо, що змінюємо в шаблонах, що виносимо в data-файли, а що закриваємо окремим плагіном. Розкладаємо стилі за шарами, щоб правки не ламали сусідні блоки.
3. Налаштування шаблонів і стилів. Переписуємо layouts та includes під потрібну верстку, приводимо типографіку та сітку до єдиного вигляду, прибираємо дублювану розмітку на користь перевикористовуваних компонентів.
4. Підключення плагінів. Додаємо тільки те, що вирішує задачу: генерація колекцій, обробка зображень, карта сайту, підсвічування коду. Кожен плагін перевіряємо на сумісність з поточною гілкою та на швидкість збірки.
5. Перевірка. Збираємо сайт локально, проганяємо сторінки на биті посилання, перевіряємо виведення на різних роздільних здатностях та коректність відкату до попередньої версії теми. Окремо дивимося час збірки до та після правок.
6. Передача. Віддаємо налаштовану тему з описом структури, інструкцією з локальної збірки та списком внесених змін, щоб команда могла розвивати її без нас.

Такий порядок тримає кастомізацію передбачуваною: кожна зміна прив'язана до конкретного файлу та перевірена до передачі. Якщо під час аудиту випливають обмеження теми, ми говоримо про них одразу, а не після збірки.

Що отримує замовник: конфігурації та документація

Робота з Jekyll-темою закінчується не «виправленими стилями», а набором артефактів, за якими проєкт можна розвивати без автора правок. Нижче — що саме залишається у замовника після кастомізації.

• Файли конфігурації — _config.yml з винесеними параметрами: базова адреса, колекції, значення за замовчуванням для шаблонів, налаштування збірки. Правка контенту та структури не вимагає лізти в код.
• Схема шаблонів — карта layouts, includes і data-файлів: який шаблон за що відповідає, де точка входу, які блоки перевикористовуються. За нею новий розробник орієнтується за годину, а не за тиждень.
• Стильова система — змінні теми (кольори, типографіка, відступи) в одному місці, розбиті за шарами стилі та правило, як додавати нові компоненти, не ламаючи наявні.
• Політики доступу та ролей — хто і що може змінювати: контент, шаблони, конфігурацію збірки. Розподіл прав прибирає правки «поза процесом».
• Регламент оновлення залежностей — періодичність, порядок перевірки сумісності плагінів і генераторів, точка відкату на попередню збірку.
• Інструкція з локального запуску — як підняти проєкт, зібрати та перевірити зміни до публікації, які перевірки обов'язкові перед викладкою.
• Каталог плагінів і розширень — що підключено, навіщо і які обмеження накладає на структуру сайту.
• Журнал змін теми — що і коли змінювалося, щоб відрізняти авторські правки від оновлень.

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

Кейс: як налаштована тема прискорила збірку втричі

Проєкт — корпоративний сайт-документація на Jekyll: близько 4 000 сторінок, три мови, щоденні правки контенту від кількох авторів.

Вихідна тема була взята готовою і «доналаштована» зверху: десятки перевизначень у _sass, важкі ланцюжки успадкування шаблонів, плагіни, кожен з яких на етапі збірки перечитував увесь каталог _posts.

Повна збірка займала 11–14 хвилин, інкрементальна — близько 3 хвилин, і будь-який автор, який виправив один рядок, чекав на результат довше, ніж писав правку.

Що було до кастомізації

Заміри на чистому клоні показали, де витрачається час: більше половини — на повторний обхід колекцій і генерацію сторінок тегів, ще чверть — на компіляцію стилів через вкладені @import без розділення на критичну та відкладену частини.

Шаблони тягнули дані через site.pages цілком замість точкових вибірок за where, тому кожна сторінка заново перебирала весь список.

Що змінили

Переписали шар стилів: пласка структура партіалів, єдині змінні теми, виведення одного зібраного файлу замість каскаду перевизначень.

Плагіни замінили на вбудовані колекції з явними output: true та обмеженими вибірками, важкі обчислення винесли в окремий крок, який виконується один раз і кешується між збірками. Шаблони перевели на точкові звернення до даних і прибрали дублювальні include.

Що це дало

Автор бачить результат правки за десятки секунд замість хвилин — цикл «змінив, перевірив, запушив» перестав бути вузьким місцем. Збірка на сервері вкладається у вікно деплою, відкат на попередній реліз залишається доступним, бо артефакти збираються відтворювано.

Тема при цьому залишилася кастомізованою: новий блок або розділ додається правкою одного партіала, а не пошуком потрібного перевизначення серед десятків.

Чим відрізняється правка теми від її перевизначення?

Правка теми — це зміна файлів усередині самої теми: шаблонів, стилів, партіалів.

Перевизначення — це коли оригінал залишається недоторканим, а поруч з'являється шар, який його заміщає: свій шаблон з тим самим ім'ям, додатковий файл стилів, що підключається поверх, свій набір даних замість вбудованого. Різниця не косметична — від неї залежить, що станеться при наступному оновленні теми.

Правка виглядає швидше: відкрив потрібний шаблон, поправив розмітку, додав стиль. Проблема проявляється пізніше, коли виходить нова версія теми з виправленнями та новими можливостями.

Оновитися не можна — будь-яке оновлення затрьох ваші зміни, а порівняти їх з оригіналом уже немає з чим: незрозуміло, що було вашим, а що прийшло з теми. Через півроку ніхто в команді не пам'ятає, чому в конкретному партіалі з'явився нестандартний рядок, і чіпати його бояться.

Перевизначення будується на тому, що тема залишається незмінною та оновлюваною, а всі ваші доопрацювання живуть окремим шаром. Шаблон з тим самим ім'ям у вашому каталозі має приоритет над темою — оригінал при цьому цілий.

Стилі підключаються після теми, тому перекривають її правила без правки вихідних файлів. Логіка виноситься в окремі модулі, що підключаються, а не вбудовується в чужий код.

Стратегію обирають за горизонтом. Якщо тема разова і оновлювати її не планується — правка допустима і дешевша.

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

На практиці частіше беруть змішаний підхід — перевизначають точково там, де тема буде змінюватися, і правлять напряму в місцях, які точно не торкнуть.

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

Часті технічні сумніви під час роботи з темою

Тема — це звичайний набір шаблонів, стилів і конфігурації, тому всі сумніви зводяться до трьох речей: чи не зламається збірка після оновлення, чи не впреться генерація в розмір сайту і чи не потягне тема зайвого в готову сторінку.

Сумісність плагінів і сторонніх бібліотек

Плагіни поділяються на ті, що працюють під час збірки, і ті, що підключаються в готовій сторінці.

Перші перевіряємо на сумісність з поточною гілкою генератора та версіями залежностей, другі — на конфлікти між собою: дві бібліотеки для одного й того самого віджета часто ламають одна одну.

Кожен плагін додає час до збірки, тому залишаємо лише ті, що дають реальну функцію, а не дублюють вбудовані можливості.

Чи не стане сайт збиратися занадто довго?

Час збірки зростає разом із кількістю сторінок і плагінів, а не з обсягом окремої сторінки. Вузьке місце зазвичай — важкі операції на кожному матеріалі: генерація зображень, підсвічування коду, перерахунок пов'язаних записів.

Прискорюємо точково: кешуємо проміжні результати, виносимо разову обробку з циклу збірки, обмежуємо перезбірку лише зміненими файлами. На проєкті з кількома сотнями сторінок це повертає збірку до хвилин замість десятків хвилин.

Що з продуктивністю готових сторінок?

Статична сторінка віддається швидко, але тему легко обтяжити: зайві шрифти, невикористані стилі, скрипти, підключені на всіх сторінках без необхідності. Збираємо один оптимізований файл стилів замість десятка, відкладаємо другорядні скрипти, стискаємо зображення на етапі збірки.

У результаті сторінка віддає готову розмітку одразу, без очікування серверної логіки, а правки в контенті не потребують перезапуску застосунку.

Якщо сумнів не з цього списку — опишіть вашу ситуацію, розберемо її окремо.

Обговоримо ваше завдання з налаштування теми

Щоб налаштування теми не перетворилося на перебір гіпотез, починаємо з розбору задачі: що за сайт, хто ним користується, які розділи та типи сторінок потрібні, як публікується контент.

На дзвінку уточнюємо вихідні дані та межі робіт — після цього повертаємося з планом та оцінкою, без «зробимо гарно, а там побачимо».

Що розберемо на обговоренні:

• Поточний стан: готова тема, самописна верстка або набір шаблонів — від цього залежить обсяг кастомізації, а не переписування з нуля.
• Структуру: які колекції, типи записів і сторінки потрібні, як організовані розділи та навігація, де знадобляться власні шаблони.
• Контент і публікацію: хто і як додає матеріали, чи потрібна підтримка розмітки, автоматичне складання та попередній перегляд перед публікацією.
• Дизайн і стилі: фірмові кольори, типографіка, адаптивність під мобільні — що беремо з теми, а що перевизначаємо.
• Функціональність: форми, пошук, інтеграції, аналітика — що підключаємо штатно, а що потребує окремого рішення.
• Обмеження та терміни: пріоритети, етапність, що критично до запуску, а що можна винести в другу чергу.

За підсумками розмови фіксуємо план робіт: етапи, склад змін, точки узгодження та порядок перевірки результату. Опишіть задачу у зручній формі — повернемося з оцінкою та планом.