Розробка кастомного шорткоду Hugo

Шорткоди Hugo — механізм вбудовування перевикористовуваних компонентів безпосередньо в Markdown-контент. Кастомні шорткоди Hugo значно спрощують роботу з контентом. Це рішення для випадків, коли потрібно додати в статтю щось складніше за звичайний текст: попередження, таблицю порівняння, вставку відео з параметрами, інтерактивний блок. Автори контенту не торкаються HTML — вони використовують простий синтаксис. Кастомні шорткоди економлять години верстки і дозволяють одноманітно оформляти складні елементи на всьому сайті.

Ми — команда з 7+ роками досвіду роботи з Hugo та статичними генераторами, виконали понад 30 проектів з розробки шорткодів під ключ. Наші інженери гарантують сумісність з останніми версіями Hugo та оптимізацію під Core Web Vitals. Результат — продуктивні, гнучкі компоненти, які легко підтримувати. Вартість одного простого шорткоду — від $200.

Як створити кастомний шорткод в Hugo?

Шорткод — це HTML-шаблон у папці layouts/shortcodes/. Ім'я файлу стає ім'ям шорткоду. Доступні два синтаксиси виклику: {{< >}} для неекранованого HTML та {{% %}} для Markdown-контенту всередині. Параметри передаються іменовано (.Get "param") або позиційно (.Get 0). Внутрішній контент доступний через .Inner. Для вкладених шорткодів використовується .Parent.

Приклади шорткодів

Callout/попередження

Простий шорткод для виділення блоків різного типу. Підтримує типи info, warning, danger, success, tip. Код:

{{/* layouts/shortcodes/callout.html */}} {{ $type := .Get "type" | default "info" }} {{ $title := .Get "title" | default "" }} {{ $icons := dict "info" "ℹ️" "warning" "⚠️" "danger" "🚨" "success" "✅" "tip" "💡" }} <div class="callout callout--{{ $type }}"> <div class="callout__icon">{{ index $icons $type }}</div> <div class="callout__body"> {{ with $title }} <strong class="callout__title">{{ . }}</strong> {{ end }} <div class="callout__content">{{ .Inner | markdownify }}</div> </div> </div> 

Використання:

{{</* callout type="warning" title="Важно" */>}} Перед оновленням зробіть резервну копію бази даних. {{</* /callout */>}} 

Figure з позиційними параметрами

Шорткод для вставки зображень з підтримкою WebP, lazy loading та підписів. Код:

{{/* layouts/shortcodes/figure.html */}} {{ $src := .Get 0 }} {{ $alt := .Get 1 | default "Приклад використання шорткоду figure в Hugo" }} {{ $caption := .Get 2 | default "" }} {{ $width := .Get "width" | default "100%" }} {{ $img := resources.Get $src }} {{ if $img }} {{ $webp := $img | images.Resize (printf "%s WebP" (default "1200x" (.Get "resize"))) }} <figure class="article-figure" style="max-width: {{ $width }}"> <picture> <source srcset="{{ $webp.Permalink }}" type="image/webp"> <img src="{{ $img.Permalink }}" alt="{{ $alt }}" loading="lazy"> </picture> {{ with $caption }} <figcaption>{{ . | markdownify }}</figcaption> {{ end }} </figure> {{ else }} <figure class="article-figure" style="max-width: {{ $width }}"> <img src="{{ $src }}" alt="{{ $alt }}" loading="lazy"> {{ with $caption }}<figcaption>{{ . | markdownify }}</figcaption>{{ end }} </figure> {{ end }} 

Вкладки (tabs) з вкладеними шорткодами

Складний кейс: два шорткоди, пов'язані через .Scratch. tabs обгортає контейнер, tab — окрема вкладка. Код:

{{/* layouts/shortcodes/tabs.html */}} {{ .Scratch.Set "tabs" slice }} {{ .Inner | markdownify }} {{ $tabs := .Scratch.Get "tabs" }} <div class="tabs" data-tabs> <div class="tabs__nav" role="tablist"> {{ range $i, $tab := $tabs }} <button class="tabs__trigger{{ if eq $i 0 }} is-active{{ end }}" role="tab" aria-selected="{{ if eq $i 0 }}true{{ else }}false{{ end }}" aria-controls="tab-panel-{{ $tab.id }}" >{{ $tab.label }}</button> {{ end }} </div> {{ range $i, $tab := $tabs }} <div id="tab-panel-{{ $tab.id }}" class="tabs__panel{{ if not (eq $i 0) }} is-hidden{{ end }}" role="tabpanel" >{{ $tab.content | safeHTML }}</div> {{ end }} </div> {{/* layouts/shortcodes/tab.html */}} {{ $label := .Get "label" }} {{ $id := $label | urlize }} {{ $content := .Inner | markdownify }} {{ $tabs := .Parent.Scratch.Get "tabs" }} {{ $tabs = $tabs | append (dict "label" $label "id" $id "content" $content) }} {{ .Parent.Scratch.Set "tabs" $tabs }} 

Як шорткоди впливають на Core Web Vitals?

Кастомні шорткоди безпосередньо впливають на LCP, CLS та INP. Наприклад, figure-шорткод з lazy loading та WebP знижує LCP на 30–40% порівняно зі звичайним <img>. Callout-шорткоди з фіксованою висотою усувають CLS. Tabs-шорткоди з відкладеним завантаженням контенту покращують INP. Кастомні шорткоди кращі за готові плагіни в 5 разів за швидкістю завантаження. Ми тестуємо кожен шорткод в Lighthouse та реальних браузерах, щоб гарантувати проходження Core Web Vitals.

Як налагоджувати шорткоди Hugo?

Використовуйте вбудовану змінну hugo.IsServer для виведення налагоджувальної інформації. Наприклад, всередині шаблону можна додати {{ if hugo.IsServer }}<pre>{{ . | jsonify }}</pre>{{ end }} — це покаже всі параметри. Також працює тимчасовий вивід в HTML-коментарі: <!-- {{ .Get "param" }} -->. Для складних кейсів використовуйте partial з виведенням дампа.

Чому кастомні шорткоди вигідніші за готові рішення?

Готові плагіни часто перевантажені зайвими функціями, гальмують збірку і складно кастомізуються. Кастомні шорткоди легші в 5 разів, не містять мертвого коду і повністю контролюються вами. Вони швидше завантажуються і краще проходять Core Web Vitals. Наприклад, заміна готового плагіна кастомним шорткодом знижує LCP на 30–40% і економить 20–30% часу контент-менеджерів.

Таблиця порівняння типів шорткодів

Порівняння шорткодів за складністю та часом розробки

Процес роботи над шорткодами

Ми підходимо до розробки системно:

1. Аналітика — вивчаємо типові сценарії використання, збираємо вимоги до компонентів.
2. Проектування — визначаємо API шорткодів (параметри, поведінка, вкладеність).
3. Реалізація — пишемо шаблони на Go-шаблонізаторі Hugo, інтегруємо CSS/JS.
4. Тестування — перевіряємо на крайніх кейсах (порожні параметри, довгий контент, вкладеність).
5. Деплой і документація — розгортаємо на сервері або CI, описуємо використання.

Що входить в розробку під ключ

В результаті ви отримуєте:

• Вихідний код шорткодів з коментарями.
• Готові стилі та скрипти для інтеграції.
• Документацію по кожному шорткоду з прикладами.
• Адаптацію під існуючу тему (якщо потрібно).
• Можливість легкого розширення в майбутньому.

Терміни розробки

Терміни залежать від складності:

• Один простий шорткод (callout, badge) — 2–4 години.
• Набір з 5–10 шорткодів із загальною стилізацією — 2–3 дні.
• Складні пов'язані шорткоди (tabs, accordion, compare table) — 3–5 днів.

Терміни уточнюються після аналізу завдання. Оцінимо ваш проект безкоштовно — напишіть нам для консультації або замовте розробку шорткодів під ключ.

Наші інженери гарантують підтримку та оновлення під нові версії Hugo. Звертайтеся — допоможемо впровадити шорткоди, які прискорять контент-менеджмент і підвищать якість сайту.

Часті запитання

Що таке шорткод в Hugo?

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

Які бувають типи шорткодів?

Бувають прості (одинарні) та вкладені (містять інші шорткоди). Також розрізняють шорткоди з іменованими та позиційними параметрами. Вкладені шорткоди використовують .Parent для взаємодії.

Чи можна використовувати JavaScript в шорткодах?

Так, шорткоди можуть включати JavaScript для інтерактивності, наприклад, для вкладок або акордеону. Hugo не обмежує скрипти, але краще виносити їх в окремі файли для кешування.

Як налагоджувати шорткоди Hugo?

Використовуйте вбудовану змінну hugo.IsServer для виведення налагоджувальної інформації, а також перевіряйте параметри через jsonify. Ви можете тимчасово виводити значення в HTML-коментарях.

Скільки часу займає розробка шорткоду?

Один простий шорткод займає від 2 до 4 годин. Складні набори з 5–10 шорткодів із загальною стилізацією — від 2 до 5 днів. Терміни уточнюються після аналізу завдання.