Настройка и кастомизация темы 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 и порядок работ.

• Ссылку на текущий сайт или репозиторий темы: что уже собрано, какие шаблоны правятся, что переписывается с нуля.
• Макеты в макете-файле или хотя бы структуру страниц: блоки, их состояния, поведение на разных ширинах экрана.
• Перечень типов контента и шаблонов, которые под них нужно завести, включая повторяющиеся карточки и списки.
• Где живёт сборка: хостинг, домен, сборочный конвейер, кто из вашей команды держит доступы.
• Требования к формам и связкам с внешними системами: контент-редактор, учёт заявок, поиск, аналитика, мультиязычность.
• Ограничения и правила приёмки: поддерживаемые браузеры, требования к разметке и метаданным, кто принимает результат.

Получив это, мы возвращаемся с оценкой и планом: перечень этапов, их порядок, что нужно от вашей стороны на каждом шаге и где точки согласования. Порядок работ обычно такой: разбор вводных и текущей темы, согласование структуры шаблонов, кастомизация и стилизация, наполнение тестовым контентом, проверка на реальных сборках, передача с документацией. Если часть данных отсутствует — не страшно, доберём на созвоне, оценка от этого не сдвинется на недели.

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