Разработка кастомного шорткода Hugo: от идеи до production

Почему стандартные шорткоды Hugo ломают сборку

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

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

Второй источник падений — неявные зависимости от шаблонов. Шорткод вызывает {{ .Page.Store }} или обращается к параметрам сайта, которые есть в одной конфигурации и отсутствуют в другой. Локально всё работает, в другой ветке окружения сборка падает с невнятным сообщением. То же с параметрами самого шорткода: если не проверять их наличие и тип, опечатка в имени аргумента тихо подставит пустое значение вместо ошибки.

Третий класс проблем — обновление контента. Редактор меняет разметку, добавляет новый параметр, а старый шорткод его не знает и падает на середине сборки. Без валидации и понятных сообщений об ошибке поиск причины занимает часы: сборка останавливается на одном файле, но реальная причина — в другом. Кастомные шорткоды без тестов и без явных контрактов по параметрам превращают каждое обновление контента в риск.

Разбираем, как это закрывается: единый реестр шорткодов, валидация параметров на входе и понятные ошибки сборки вместо тихих подстановок.

Что даёт кастомная разработка шорткодов

Скорость сборки и предсказуемость вывода

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

Меньше ручного труда редакторов

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

Надёжность шаблонов и контроль ошибок

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

Автоматизация повторяющихся сценариев

Шорткоды закрывают типовые задачи контента: вставку данных из внешнего источника, расчёт значений, генерацию оглавления, единый формат карточек и кнопок. Логика описывается один раз и переиспользуется, поэтому новый раздел собирается из готовых блоков, а не пишется с нуля. В сумме это даёт предсказуемый результат: сборка быстрее, редакторы тратят время на смысл, а не на разметку, а класс ошибок вёрстки уходит на уровне шаблона.

Сравнение подходов к реализации шорткодов

Когда Hugo не покрывает задачу встроенными средствами, у команды остаётся три пути: обойтись штатными шорткодами, вынести логику в partials или подключить внешний модуль. Выбор диктует не вкусовщина, а то, где живёт логика шаблона и кто её будет сопровождать через полгода.

Где проходит граница

Встроенные шорткоды закрывают 80% контентных задач без единой строки своего кода — если автору нужно вставить код или цитату, писать partial незачем. Как только появляется повторяющийся блок с параметрами (карточка товара, врезка с метрикой, таблица сравнения), логика переезжает в partial: он принимает именованные аргументы и возвращает готовую разметку, а вызывающий markdown остаётся читаемым.

Когда оправдан внешний модуль

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

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

Этапы внедрения кастомных шорткодов

Внедрение кастомного шорткода начинается не с кода, а с инвентаризации того, что уже есть в контенте. Мы выгружаем все страницы, находим повторяющиеся блоки — врезки, таблицы сравнения, блоки с ценами, встроенные формы — и считаем, сколько раз каждый встречается и в скольких вариантах разметки. Это даёт точный список того, что стоит автоматизировать, и отсекает шорткоды «на будущее», которые никто не вызовет.

Дальше проектируем интерфейс вызова: какие параметры обязательные, какие имеют значения по умолчанию, что передаётся позиционно, а что именованно. Здесь же фиксируем, как шорткод ведёт себя при неполных данных — падает сборка или подставляется заглушка. От этого зависит, сможет ли редактор без знания Go-шаблонов собрать страницу, не сломав остальные.

1. Аудит контента — выгрузка страниц, поиск повторяющихся блоков, замер частоты и вариантов разметки.
2. Проектирование интерфейса — список параметров, значения по умолчанию, правила валидации, поведение при ошибке.
3. Реализация — шаблон шорткода, partial-компоненты, стили в изолированном слое, чтобы не задеть существующую вёрстку.
4. Тестирование — сборка на реальном контенте, проверка крайних случаев: пустые поля, длинный текст, вложенные шорткоды, вывод в RSS и sitemap.
5. Документация — примеры вызова с копируемыми фрагментами, описание параметров, типовые ошибки и что делать.
6. Передача — обучение редакторов, разбор на живых страницах, ответы на вопросы по ходу правок.
7. Сопровождение — правки шаблона при изменении дизайна, добавление параметров без переписывания уже опубликованных страниц.

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

Артефакты, которые получает заказчик

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

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

Комплект рассчитан на то, что новый инженер входит в проект по документации, а не по переписке. Если часть артефактов у вас уже есть — обсудим задачу и соберём недостающее.

Кейс: ускорение сборки и снижение ошибок

Проект — корпоративный портал на Hugo: несколько тысяч страниц контента, десятки авторов из разных отделов, ежедневные правки. Изначально редакторы собирали типовые блоки — карточки товаров, таблицы характеристик, врезки с призывами — вручную через HTML. Каждая новая страница тянула за собой копипаст разметки, а любая правка шаблона означала проход по всему корпусу текстов.

Что было до

Полная сборка занимала 11-14 минут: генератор пересобирал все страницы целиком, потому что кэш сбрасывался из-за нестабильных включений. Ошибки вёрстки ловились уже на этапе вычитки — в среднем 8-12 дефектов на релиз: незакрытые теги, разъехавшиеся таблицы, потерянные классы. Редакторы тратили на разметку одной страницы около 40 минут и не могли проверить результат без разработчика.

Что изменили

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

Что стало

Полная сборка сократилась до 2-3 минут, инкрементальная — до нескольких секунд. Ошибки вёрстки на релиз упали с 8-12 до 0-2: типовые дефекты теперь физически невозможно внести, разметку генерирует шаблон, а не человек. Редакторы собирают страницу за 5-7 минут без участия разработчика — правки контента перестали быть задачей команды.

Чем отличаются шорткоды Hugo от других генераторов?

Ключевое отличие в том, что шорткод — это не отдельный плагин или внешний модуль, а часть шаблонизатора. В Hugo он объявляется как обычный шаблон в каталоге layouts/shortcodes/, вызывается прямо из тела markdown и получает на вход параметры через именованные аргументы или позиционные значения. Никакого реестра расширений, никакой регистрации в конфиге — движок сам находит файл по имени и подставляет результат на этапе сборки. Именно поэтому hugo shortcodes работают одинаково и в локальной сборке, и в конвейере публикации.

Сравнение генераторов показывает разницу в подходе к шаблонизации. В Jekyll вставки делаются через Liquid-теги и плагины на Ruby, которые нужно ставить и поддерживать отдельно — при смене окружения сборка ломается. В Eleventy логика живёт в коротких кодах на JavaScript, и это гибко, но привязывает контент к рантайму. В Astro и Next вставки — это компоненты фреймворка, что тянет за собой полноценный слой зависимостей. Hugo в этом смысле ближе к «чистому» генератору: шорткод остаётся шаблоном, а не программой.

Есть и практическое следствие для сопровождения. Шорткоды наследуют контекст страницы — могут читать её параметры, ресурсы и данные сайта, поэтому один и тот же вызов даёт разный результат на разных страницах без дублирования разметки. Вложенные шорткоды вызывают друг друга, а встроенные (вставка кода, ссылки на файлы, разметка блоков) уже покрывают типовые задачи. В других генераторах аналогичное поведение часто требует обходных путей.

Наконец, отличия проявляются в предсказуемости. Шорткод компилируется вместе с сайтом, ошибка в нём останавливает сборку с указанием файла и строки, а не всплывает в браузере у посетителя. Для проектов, где контент обновляют редакторы без доступа к коду, это снимает целый класс инцидентов: разметка остаётся валидной, потому что её формирует шаблон, а не ручной ввод.

Частые технические сомнения

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

Насколько это бьёт по скорости сборки?

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

Что с нестандартными сценариями — калькуляторы, формы, динамика?

Шорткод отдаёт статичную разметку, поэтому интерактив выносим в отдельный скрипт, который подключается точечно и не блокирует отрисовку. Такой подход сохраняет скорость статики и даёт нужную динамику: калькулятор считает на клиенте, форма уходит на наш обработчик. Логику держим в одном месте, чтобы правка не расползалась по десяткам страниц.

Как это поддерживать, если автор уйдёт?

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

Обсудим вашу задачу по шорткодам

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

Что обычно обсуждаем на первом разговоре:

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

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

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

Как читать таблицу. Готовые решения выигрывают на старте, но проигрывают, когда контента становится больше, а обновления выходят регулярно. Самописный вариант подходит командам с сильным разработчиком в штате. Кастомная разработка с поддержкой окупается там, где важны предсказуемость сборки и отсутствие простоев при обновлениях.