Налаштування та кастомізація теми Eleventy під ключ

Кастомізація теми Eleventy: де ламається збірка

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

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

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

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

Третє — биті сторінки через втрачені зв’язки. Сторінка поза колекцією не отримує адресу, посилання в меню веде в нікуди, а шаблон даних з одруком в імені поля віддає порожній список там, де очікувався каталог. Помилка не спливає до перегляду конкретного розділу.

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

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

Вимірюваний ефект: збірка, вага сторінок, стабільність

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

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

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

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

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

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

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

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

Варіанти налаштування теми: від готової до власної

В Eleventy тема — це не моноліт, а зв’язка layouts, includes, колекцій і правил обробки даних. Тому підхід визначається одним: наскільки структура контенту збігається з типовою, закладеною автором теми.

Межа проходить за кількістю типів сторінок і джерел даних: одне джерело і 3–5 типів вкладаються в готову тему, десять типів, власна сітка й мультимовність потребують власної. Чим пізніше зроблено перехід на наступний варіант, тим дорожче він обходиться.

Етапи налаштування Eleventy: від аудиту до передачі

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

1. Аудит шаблонів. Розбираємо дерево шаблонів і дублі розмітки, дивимося, які колекції збираються з front matter, а які — із зовнішніх джерел. Результат — карта шаблонів і список місць, які ламаються під час додавання нового типу сторінки.

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

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

4. Кастомізація теми. Розкладаємо розмітку на перевикористовувані блоки, типографіку й сітку — у змінні. Зміна логотипа, палітри або структури меню перестає бути правкою в десятку файлів.

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

6. Передача проєкту. Віддаємо репозиторій з історією, конфіг, схеми, інструкцію з додавання сторінок і записи щодо встановлення. Навчання проводимо на реальному завданні редактора.

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

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

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

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

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

З практики: перенесення каталогу на статичну збірку

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

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

Що було до перенесення

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

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

Що стало після

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

Збірку веде Eleventy, тому повний прогін по 4 800 картках займає близько двох хвилин, а правка однієї картки перезбирає лише її залежності. Час відповіді сторінки впав із секунд до десятків мілісекунд, викладення змін скоротилося з пів години до трьох хвилин.

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

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

Чим відрізняється доопрацювання теми Eleventy від нової розробки?

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

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

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

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

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

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

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

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

Чи зможемо правити контент без розробника?

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

Що робити з чужим кодом у проєкті?

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

Як передаються доступи?

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

Що з оновленнями теми?

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

Обговоримо завдання: що надіслати й як піде робота

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

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

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

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

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

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