Чому стандартні шорткоди Hugo ламають збірку
Стандартний набір шорткодів закриває типові завдання — вставлення зображення, посилання на іншу сторінку, коротку цитату. Проблеми починаються, коли контент-команда просить «ще трохи»: вкладену галерею, блок із параметрами, таблицю із зовнішнього джерела.
Кожен такий запит хтось закриває новим шорткодом, і через півроку в проєкті живе кілька десятків шаблонів, про які ніхто не пам'ятає, хто їх створив і навіщо.
Перше, об що спотикається збірка, — конфлікти імен. Hugo шукає шаблон шорткоду в кількох місцях: у темі, в проєкті, у вкладених каталогах. Якщо два шаблони називаються однаково, перемагає той, чий шлях вищий у порядку пошуку, — і це не завжди той, який мав на увазі автор.
Помилка проявляється не відразу: сторінка збирається, але рендериться чужим шаблоном, а розходження помічають уже на проді.
Друге джерело падінь — неявні залежності від шаблонів. Шорткод викликає {{ .Page.Store }} або звертається до параметрів сайту, які є в одній конфігурації та відсутні в іншій. Локально все працює, в іншій гілці середовища збірка падає з незрозумілим повідомленням.
Те саме з параметрами самого шорткоду: якщо не перевіряти їхню наявність і тип, одруківка в імені аргументу тихо підставить порожнє значення замість помилки.
Третій клас проблем — оновлення контенту. Редактор змінює розмітку, додає новий параметр, а старий шорткод його не знає і падає на середині збірки.
Без валідації та зрозумілих повідомлень про помилку пошук причини займає години: збірка зупиняється на одному файлі, але реальна причина — в іншому. Кастомні шорткоди без тестів і без явних контрактів за параметрами перетворюють кожне оновлення контенту на ризик.
Розбираємо, як це закривається: єдиний реєстр шорткодів, валідація параметрів на вході та зрозумілі помилки збірки замість тихих підстановок.
Що дає кастомна розробка шорткодів
Швидкість збірки та передбачуваність виводу
Кастомний шорткод — це функція шаблонізатора, яка на етапі збірки перетворює коротку конструкцію на готову розмітку. Замість важкого вбудовування чужого коду ви описуєте правило один раз, і генератор збирає сторінку з підготовлених фрагментів.
На типовому проєкті це прискорює повну збірку в рази: чим більше однотипних блоків, тим помітніший розрив, бо робота йде за однією схемою, а не перезбіркою кожного елемента.
Менше ручної праці редакторів
Редактор вставляє один рядок з параметрами — таблицю, галерею, врізку з цитатою — і не думає про розмітку. Оформлення, відступи та адаптивність підставляються з шаблону автоматично, тому правки контенту не ламають верстку.
Один і той самий блок на десяти сторінках виглядає ідентично, а зміна дизайну робиться в одному місці й розходиться по всьому сайту.
Надійність шаблонів і контроль помилок
Коли розмітка живе в шаблоні, а не в тексті, зникає цілий клас помилок: незакриті теги, забуті атрибути, роз'їхалися відступи.
Некоректні параметри відловлюються на етапі збірки — сторінка або збирається правильно, або збірка падає з зрозумілою помилкою, а не віддає відвідувачу зламаний блок. Це знижує частку ручних перевірок і прибирає залежність результату від акуратності конкретного автора.
Автоматизація повторюваних сценаріїв
Шорткоди закривають типові завдання контенту: вставку даних із зовнішнього джерела, розрахунок значень, генерацію змісту, єдиний формат карток і кнопок. Логіка описується один раз і перевикористовується, тому новий розділ збирається з готових блоків, а не пишеться з нуля.
У сумі це дає передбачуваний результат: збірка швидша, редактори витрачають час на сенс, а не на розмітку, а клас помилок верстки зникає на рівні шаблону.
Порівняння підходів до реалізації шорткодів
Коли Hugo не покриває завдання вбудованими засобами, у команди залишається три шляхи: обійтися штатними шорткодами, винести логіку в partials або підключити зовнішній модуль. Вибір диктує не смаківщина, а те, де живе логіка шаблону і хто її супроводжуватиме через пів року.
| Підхід | Коли підходить | Обмеження |
|---|---|---|
| Вбудовані шорткоди | Типові завдання: вставка коду, цитати, вбудовування медіа, розмітка всередині markdown | Логіка фіксована ядром, кастомізація лише через параметри виклику |
| Кастомні через partials | Повторювані блоки з параметрами: картки, таблиці порівняння, врізки з даними з front matter | Вимагає дисципліни в іменуванні та передачі контексту, інакше шаблони розходяться |
| Зовнішні модулі | Спільна логіка між кількома сайтами, версіонування та перевикористання між проєктами | Залежність від зовнішнього репозиторію, накладні витрати на оновлення та сумісність |
Де проходить межа
Вбудовані шорткоди закривають 80% контентних завдань без жодного рядка власного коду — якщо автору потрібно вставити код або цитату, писати partial немає сенсу.
Щойно з'являється повторюваний блок з параметрами (картка товару, врізка з метрикою, таблиця порівняння), логіка переїжджає в partial: він приймає іменовані аргументи і повертає готову розмітку, а викликаючий markdown залишається читабельним.
Коли виправданий зовнішній модуль
Зовнішній модуль має сенс, коли один і той самий шорткод потрібен на кількох сайтах і має оновлюватися централізовано. Ціна — керування версіями та контроль сумісності: оновлення модуля може зламати розмітку на одному з сайтів, і це потрібно ловити до публікації. Для одиночного проєкту такий підхід додає зв'язності більше, ніж користі.
Розбираємо, як вибрати підхід під конкретне завдання і не закласти технічний борг на старті.
Етапи впровадження кастомних шорткодів
Впровадження кастомного шорткоду починається не з коду, а з інвентаризації того, що вже є в контенті.
Ми вивантажуємо всі сторінки, знаходимо повторювані блоки — врізки, таблиці порівняння, блоки з цінами, вбудовані форми — і рахуємо, скільки разів кожен зустрічається і в скількох варіантах розмітки.
Це дає точний список того, що варто автоматизувати, і відсікає шорткоди «на майбутнє», які ніхто не викличе.
Далі проєктуємо інтерфейс виклику: які параметри обов'язкові, які мають значення за замовчуванням, що передається позиційно, а що іменовано. Тут же фіксуємо, як шорткод поводиться за неповних даних — падає збірка чи підставляється заглушка. Від цього залежить, чи зможе редактор без знання Go-шаблонів зібрати сторінку, не зламавши решту.
- Аудит контенту — вивантаження сторінок, пошук повторюваних блоків, замір частоти та варіантів розмітки.
- Проєктування інтерфейсу — список параметрів, значення за замовчуванням, правила валідації, поведінка при помилці.
- Реалізація — шаблон шорткоду, partial-компоненти, стилі в ізольованому шарі, щоб не зачепити наявну верстку.
- Тестування — збірка на реальному контенті, перевірка крайніх випадків: порожні поля, довгий текст, вкладені шорткоди, вивід у RSS і sitemap.
- Документація — приклади виклику з копійованими фрагментами, опис параметрів, типові помилки та що робити.
- Передача — навчання редакторів, розбір на живих сторінках, відповіді на запитання під час правок.
- Супровід — правки шаблону при зміні дизайну, додавання параметрів без переписування вже опублікованих сторінок.
Ключова вимога до процесу — зворотна сумісність. Новий параметр додається зі значенням за замовчуванням, тому старі виклики продовжують збиратися без правок контенту.
Якщо шорткод застаріває, ми не видаляємо його одразу, а позначаємо і ведемо міграцію сторінок поступово — збірка залишається зеленою на кожному кроці.
Артефакти, які отримує замовник
Робота над кастомним шорткодом закінчується не демонстрацією на тестовій сторінці, а набором артефактів, за якими команда замовника зможе розвивати рішення без нас. Нижче — що саме передається і навіщо кожен пункт потрібен на практиці.
- Вихідний код шорткодів — репозиторій із шаблонами та допоміжною логікою, розкладений за призначенням, а не одним файлом. До кожного шорткоду додано набір параметрів із типами та значеннями за замовчуванням: редактор бачить, що можна передати, і не ламає вивід друкарською помилкою в імені аргументу.
- Схеми даних — опис структур, які шорткод приймає та повертає: які поля обов'язкові, які опціональні, як пов'язані між собою. Це основа для валідації: некоректний ввід відсікається на етапі збірки, а не перетворюється на порожній блок на живій сторінці.
- Приклади використання — готові фрагменти розмітки для типових сценаріїв: таблиця, врізка, галерея, вбудований блок із зовнішнього джерела. Редактор копіює приклад і змінює вміст, замість того щоб збирати виклик з нуля.
- Посібник редактора — короткий документ мовою контент-команди: що робить кожен шорткод, які параметри приймає, що станеться при помилці. Без нього знання залишається в розробника і йде разом із ним.
- Регламент оновлення — порядок правок: де змінювати шаблон, як перевіряти сумісність із уже опублікованими матеріалами, які перевірки проганяються перед викладкою. Окремо фіксуємо, що робити при зміні версії генератора.
- Набір перевірок і тестові сторінки — збірка, яка падає при несумісній зміні, та еталонні сторінки з кожним варіантом виводу. Регрес ловиться до публікації, а не за скаргою читача.
- Інструкція з розгортання — як підняти збірку на вашій стороні: залежності, змінні середовища, команди локального запуску та викладки.
Комплект розрахований на те, що новий інженер входить у проєкт за документацією, а не за листуванням. Якщо частина артефактів у вас уже є — обговоримо задачу і зберемо те, чого бракує.
Кейс: прискорення збірки та зменшення помилок
Проєкт — корпоративний портал на 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 шукає шаблон за іменем у layouts/shortcodes/, і при збігу з темою пріоритет у проєкту. Ми тримаємо власні шорткоди в окремому просторі імен, щоб оновлення теми не перетирало логіку.
Якщо шорткод вставляє розмітку, яка перетинається з чужими стилями, ізолюємо її через scoped-класи і не чіпаємо глобальні селектори.
Наскільки це б'є по швидкості збірки?
Один шорткод додає частки мілісекунди на сторінку, але якщо всередині цикл по зовнішньому джерелу — збірка починає чекати мережу. Тому дані тягнемо один раз через окремий крок і кешуємо у файл, а шорткод читає вже локальні дані.
На проєктах із тисячами сторінок це різниця між збіркою за секунди і збіркою, яка впирається в ліміти зовнішнього сервісу.
Що з нестандартними сценаріями — калькулятори, форми, динаміка?
Шорткод віддає статичну розмітку, тому інтерактив виносимо в окремий скрипт, який підключається точково і не блокує відрисовку. Такий підхід зберігає швидкість статики і дає потрібну динаміку: калькулятор рахує на клієнті, форма йде на наш обробник. Логіку тримаємо в одному місці, щоб правка не розповзалася по десятках сторінок.
Як це підтримувати, якщо автор піде?
Кожен шорткод — це файл із зрозумілим іменем і параметрами, описаними в документації поруч із кодом. Ми фіксуємо контракт: які аргументи приймає, що повертає, де використовується. Новий розробник бачить список шорткодів, читає опис і править потрібний, не розбираючи весь проєкт. При оновленні Hugo перевіряємо сумісність на тестовій збірці до викату.
Обговоримо ваше завдання щодо шорткодів
Опишіть завдання — повернемося з оцінкою та планом. Щоб розмова була предметною, достатньо пари абзаців: який сайт, що саме не виходить штатними засобами і який результат потрібен на виході. Далі наші інженери поставлять уточнювальні запитання та запропонують варіанти реалізації.
Що зазвичай обговорюємо на першій розмові:
- Яке завдання має закривати шорткод: вставка повторюваного блоку, параметризований компонент, виведення даних із зовнішнього джерела.
- Де саме він буде використовуватися: у контенті редакторами, у шаблонах, у зв'язці з генератором статичних сторінок.
- Які параметри мають бути на вході і як редактор буде їх задавати без правки коду.
- Як шорткод поводиться під час збірки: швидкість генерації, кешування, вплив на час публікації.
- Що зі зворотною сумісністю: як оновлювати логіку, не переписуючи вже опубліковані матеріали.
- Хто буде підтримувати рішення після запуску і чи потрібна документація для редакторів.
- Як перевіряємо результат: тестові сторінки, порівняння виведення до і після, критерії приймання.
За підсумками розмови ви отримаєте оцінку проєкту та план робіт з етапами, строками та зонами відповідальності. Якщо завдання типове, запропонуємо готове рішення; якщо ні — покажемо, як вбудуємо шорткод у поточну структуру сайту без ламання наявних сторінок.
Консультація інженера — це розбір саме вашого випадку, а не загальні слова: ми дивимося на поточні шаблони, конфігурацію та контент, тому оцінка спирається на реальний обсяг робіт. Опишіть завдання — повернемося з планом і пропозицією.
