Уявіть: ви додаєте галерею з 20 знімків до статті. Без шорткодів це десятки рядків HTML з обгортками, класами, data-атрибутами та посиланнями на мініатюри. Зі шорткодом, один рядок [gallery]. Саме заради такого контрасту між обсягом рутини та результатом у WordPress 2.5 з’явилися шорткоди, і через майже два десятиліття механізм залишається незамінним.

Проблема в тому, що більшість користувачів або бояться шорткодів як «програмістської магії», або копіюють їх навмання, не вникаючи в синтаксис. А тим часом один кастомний шорткод здатен замінити плагін на сорок мегабайт або зекономити годину рутини на місяць. Цей розбір, від вбудованих [gallery] і [audio] до власного шорткоду у functions.php, дасть вам повний контроль над інструментом.

💡 Швидкий огляд:

• Що таке шорткод: тег у квадратних дужках, який WordPress замінює на результат PHP-функції під час завантаження сторінки.
• Вбудовані шорткоди: gallery, audio, video, caption, embed та playlist працюють одразу після встановлення WordPress, без плагінів.
• Параметри шорткодів: синтаксис key="value" дає змогу налаштовувати вивід без зміни коду.
• Створення власного шорткоду: від простого замінника URL до шорткоду зображення з атрибутами, готовий PHP-код для functions.php.
• Шорткоди у віджетах і шаблонах: як увімкнути підтримку одним рядком і де це стає в пригоді.

Що таке шорткод і як він влаштований

Шорткод — це короткий тег у квадратних дужках, який WordPress замінює результатом виконання PHP-функції в момент виведення сторінки. Ви пишете [gallery] у редакторі, відвідувач бачить акуратну сітку зображень. Жодної магії: за кожним шорткодом стоїть функція, зареєстрована через add_shortcode() в ядрі, темі або плагіні.

Ключова відмінність від статичних HTML-вставок: шорткод виконується на стороні сервера. Ви передаєте йому параметри, і результат формується динамічно. Змінюється контент, змінюється вивід, без правлення десятків сторінок вручну.

З погляду редактора є нюанс. Візуальний редактор (Gutenberg або класичний TinyMCE) негайно рендерить шорткод у прев’ю, тому для роботи з параметрами та вкладеними тегами перемикайтеся в текстовий режим. Тільки там видно реальну структуру: відкривний тег, атрибути, вміст, закривний тег.

Вбудовані шорткоди WordPress: що доступно без плагінів

WordPress постачається з шістьма зареєстрованими шорткодами. Їх не потрібно вмикати чи налаштовувати, просто вставляєте в запис і отримуєте результат.

Найгнучкіший із них, [gallery]. Атрибут ids дає змогу вказати конкретні зображення за ID, навіть ті, що не прикріплені до поточного запису. Атрибут size задає розмір мініатюр (thumbnail, medium, large або full). Комбінація цих двох параметрів покриває більшість сценаріїв, заради яких раніше ставили окремий плагін галереї.

[audio] і [video] підтримують множинні джерела, браузер сам обере сумісний формат. Плейлисти через [playlist] збираються з ID вкладень аналогічно до галереї, але виводять плеєр із перемиканням треків.

Параметри шорткодів: як керувати виводом

Більшість шорткодів приймають атрибути у форматі key="value". Підстановка значень змінює логіку роботи функції без втручання в код.

Візьмімо [gallery]. Без параметрів він показує всі зображення запису в стандартному розмірі. Додаємо конкретики:

1
[gallery ids="12,34,56" size="large" columns="3"]

Тепер вивід обмежено трьома вказаними зображеннями, розмір збільшено до large, а сітку вишикувано в три колонки. Параметри можна комбінувати довільно, ті, що не вказані, отримують значення за замовчуванням.

Деякі шорткоди використовують відкривний і закривний теги, коли між ними потрібно передати вміст. Скажімо, плагін Google Maps може очікувати конструкцію виду:

1
[maps]Нью-Йорк, США[/maps]

Закривний тег завжди починається з косої риски /. WordPress використовує цю нотацію, щоб відрізнити контент між тегами від атрибутів усередині відкривного тега.

Як створити власний шорткод

Коли ви десятий раз за тиждень вставляєте в статтю одну й ту саму URL-адресу, HTML-блок або call-to-action, саме час написати шорткод. Це не вимагає бути PHP-розробником: базова конструкція вміщається в три рядки.

Простий шорткод для URL

Додайте цей код у кінець файлу functions.php вашої теми (Зовнішній вигляд → Редактор теми → functions.php):

1
function techblog_short_url() {
2
    return 'https://techblog.sdstudio.top';
3
}
4
add_shortcode( 'techblog', 'techblog_short_url' );

Тепер у будь-якому записі [techblog] автоматично заміниться на URL сайту. Функція повертає рядок, WordPress підставляє його замість шорткоду.

Два критично важливих правила з офіційної документації:

• Функція повертає значення через return, а не виводить через echo. Прямий вивід ламає порядок рендерингу та призводить до неочікуваних результатів.
• Реєструйте шорткоди на хуку init, щоб WordPress встиг завантажити всі залежності:

1
add_action( 'init', 'techblog_register_shortcodes' );
2
function techblog_register_shortcodes() {
3
    add_shortcode( 'techblog', 'techblog_short_url' );
4
}

Шорткод для зображення з настроюваними атрибутами

Трохи складніший сценарій: ви хочете вставляти зображення, задаючи ширину та висоту прямо в редакторі. У functions.php:

1
function techblog_img_shortcode( $atts, $content = null ) {
2
    $atts = shortcode_atts(
3
        array(
4
            'width'  => '',
5
            'height' => '',
6
        ),
7
        $atts,
8
        'img'
9
    );
10
    return '<img src="' . esc_url( $content ) . '" width="' . esc_attr( $atts['width'] ) . '" height="' . esc_attr( $atts['height'] ) . '" alt="" />';
11
}
12
add_shortcode( 'img', 'techblog_img_shortcode' );

Використання в редакторі:

1
[img width="800" height="600"]https://example.com/photo.jpg[/img]

Функція shortcode_atts() змішує передані атрибути зі значеннями за замовчуванням — це стандартний і безпечний спосіб обробки параметрів. Зверніть увагу на esc_url() та esc_attr(): екранування обов'язкове під час виведення користувацького вводу на frontend. Повний перелік доступних атрибутів зображення є в специфікації W3C.

Окремо варто сказати про валідацію атрибутів. Коли ви приймаєте значення від редактора та підставляєте їх у HTML, завжди перевіряйте тип даних. Для числових атрибутів на кшталт width і height використовуйте intval(), це відсіче випадкові літери. Для рядків задавайте допустимий набір значень через in_array(), наприклад розміри мініатюр (thumbnail, medium, large). Так верстка залишиться цілою, а результат на frontend-і буде передбачуваним, навіть якщо автор помилиться у значенні атрибута.

Шорткоди в текстових віджетах і PHP-файлах

З версії WordPress 4.9 (листопад 2017) шорткоди автоматично працюють у текстових віджетах. Але якщо ви використовуєте кастомну тему без вбудованої підтримки, увімкнути її можна одним рядком у functions.php:

1
add_filter( 'widget_text', 'do_shortcode' );

Щоб уникнути автоматичної вставки тегів <p> і <br> навколо шорткоду у віджеті (WordPress автоформатує перенесення рядків), додайте також:

1
add_filter( 'widget_text', 'shortcode_unautop' );

Цей самий принцип працює для PHP-шаблонів. Якщо потрібно виконати шорткод прямо в header.php або іншому файлі теми, обгорніть його в do_shortcode():

1
echo do_shortcode( '[techblog]' );

Так одна й та сама логіка доступна і в редакторі, і у віджеті, і в шаблоні, без дублювання коду.

Екранування: як показати текст шорткоду без виконання

Іноді потрібно не виконати шорткод, а показати його синтаксис читачеві, як у цій статті. Якщо просто вставити [gallery] у редактор, WordPress негайно його виконає або покаже плейсхолдер. Є два способи цього уникнути.

Подвійні квадратні дужки. Найпростіший метод, подвоїти зовнішні дужки:

1
[[gallery]]

Для парних тегів подвоюються перша відкривна та остання закривна:

1
[[maps]Нью-Йорк, США[/maps]]

HTML-коди символів. У текстовому редакторі можна замінити дужки їхніми ASCII-кодами: [ замість [ і ] замість ]. Запис [gallery] відобразиться як текст [gallery], але виконаний не буде.

Перший спосіб простіший і читабельніший у вихідному коді, другий надійніший за складного форматування. Обирайте подвійні дужки для швидких правок у текстовому редакторі та ASCII-коди, коли шорткод межує з іншими квадратними дужками, наприклад, усередині блоків коду або описів мета-полів. В обох випадках відвідувач сайту бачить саме текст шорткоду, а WordPress не виконує його.

Відео: повний розбір шорткодів WordPress

Для тих, хто віддає перевагу візуальному поясненню, тримайте детальний туторіал від команди Kinsta. Автор показує створення, налагодження та реальні приклади шорткодів у живому проєкті, від встановлення теми до виведення на фронтенд.

⁉️🤔 Часті запитання

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

Так, через блок «Shortcode» на панелі додавання блоків. Ви вставляєте шорткод у поле блоку, і WordPress виконує його під час рендерингу. Однак складні шорткоди з вкладеним контентом можуть працювати непередбачувано, у таких випадках надійніше перемкнутися в режим редагування коду. Gutenberg рендерить шорткоди через серверний callback, тому результат залежить від того, чи повертає функція коректний HTML. Блокові теми (Full Site Editing) з theme.json можуть частково обмежувати виведення шорткодів у шаблонах, перевіряйте сумісність конкретної теми.

Що робити, якщо шорткод не працює?

Перевірте три типові причини. Перше: ви вставили шорткод у візуальному редакторі, який перетворив дужки на HTML-entities, перемкніться в текстовий режим і переконайтеся, що дужки прямі. Друге: плагін, що реєструє шорткод, деактивовано, зайдіть у «Плагіни» та перевірте статус. Третє: у функції шорткоду використовується echo замість return, це помилка розробника, виведення з’являється не в тому місці сторінки. Системний спосіб діагностики: відкрийте wp-config.php, увімкніть WP_DEBUG і WP_DEBUG_LOG. Після завантаження сторінки зі шорткодом перевірте wp-content/debug.log, там будуть конкретні помилки PHP із зазначенням файлу та рядка.

Чи можна вставити PHP-код прямо в шорткод?

Ні. Шорткод — це тригер, а не контейнер для довільного коду. Виконується функція, зареєстрована на стороні сервера через add_shortcode(). Якщо потрібна кастомна логіка, пишіть її у functions.php (або в окремому плагіні) та прив’язуйте до шорткоду. Між квадратними дужками можна передавати лише контент і атрибути, а не виконуваний код. Для безпечного виконання PHP у контенті вивчіть плагіни типу «Code Snippets», вони дають змогу керувати сніпетами через інтерфейс адмінки без правки functions.php і з захистом від фатальних помилок.

Шорткоди сповільнюють сайт?

Самі по собі, ні. add_shortcode() лише реєструє відповідність тега та функції в глобальному масиві $shortcode_tags. Накладні витрати виникають, коли функція шорткоду виконує важкі запити до бази даних або зовнішніх API під час кожного завантаження сторінки. Проблема не в механізмі шорткодів, а в реалізації конкретного плагіна. Орієнтир: якщо сторінка містить 20+ шорткодів, кожен із яких смикає WP_Query або wp_remote_get(), кешуйте результати через Transients API. Для типових сценаріїв (один-два шорткоди на сторінку) вплив на продуктивність є нехтовно малим.

Як видалити шорткод із виведення, не видаляючи його із запису?

Використовуйте remove_shortcode() у functions.php. Наприклад, щоб вимкнути вбудовану галерею: remove_shortcode( 'gallery' ). Після цього [gallery] у тексті запису відобразиться як звичайний текст у квадратних дужках, без виконання. Стане в пригоді під час міграції на інше рішення або налагодження конфліктів. Часткове вимкнення: можна перевизначити шорткод, зареєструвавши свій обробник із тим самим тегом через add_shortcode(). Останній зареєстрований обробник має пріоритет.

Чи варто вчити шорткоди у 2026 році

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

Якщо ви регулярно повторюєте в статтях один і той самий HTML-блок, посилання або шаблон, витратьте 10 хвилин на add_shortcode() у functions.php. Повернення інвестицій: десятки годин на рік, які ви не витрачаєте на копіпаст. Шорткоди зворотно сумісні, написаний сьогодні код працюватиме в наступних версіях WordPress, тому що API шорткодів не змінювалося з моменту появи і залишається одним із найстабільніших елементів ядра.