Wyobraźmy sobie: dodaje Pan/Pani galerię z 20 zdjęć do artykułu. Bez shortcode’ów to dziesiątki linii HTML z wrapperami, klasami, atrybutami data i odnośnikami do miniatur. Z shortcode’em, jedna linia [gallery]. Właśnie dla takiego kontrastu między ilością rutyny a rezultatem w WordPress 2.5 pojawiły się shortcode’y i po niemal dwóch dekadach mechanizm ten pozostaje niezastąpiony.

Problem w tym, że większość użytkowników albo boi się shortcode’ów jako „programistycznej magii", albo kopiuje je na chybił trafił, nie zagłębiając się w składnię. A tymczasem jeden niestandardowy shortcode może zastąpić czterdziestomegabajtową wtyczkę lub zaoszczędzić godzinę rutyny miesięcznie. Ta analiza, od wbudowanych [gallery] i [audio] po własny shortcode w functions.php, da Panu/Pani pełną kontrolę nad tym narzędziem.

💡 Szybki przegląd:

• Czym jest shortcode: znacznik w nawiasach kwadratowych, który WordPress zastępuje wynikiem funkcji PHP podczas ładowania strony.
• Wbudowane shortcode’y: gallery, audio, video, caption, embed i playlist działają od razu po instalacji WordPressa, bez wtyczek.
• Parametry shortcode’ów: składnia key="value" umożliwia dostosowanie wyniku bez zmiany kodu.
• Tworzenie własnego shortcode’u: od prostego zamiennika URL po shortcode obrazu z atrybutami, gotowy kod PHP do functions.php.
• Shortcode’y w widgetach i szablonach: jak włączyć obsługę jedną linijką i gdzie się to przydaje.

Czym jest shortcode i jak jest zbudowany

Shortcode to krótki znacznik w nawiasach kwadratowych, który WordPress zastępuje wynikiem wykonania funkcji PHP w momencie renderowania strony. Pisze Pan/Pani [gallery] w edytorze, a odwiedzający widzi schludną siatkę obrazów. Żadnej magii: za każdym shortcode’em stoi funkcja zarejestrowana przez add_shortcode() w jądrze, motywie lub wtyczce.

Kluczowa różnica w porównaniu ze statycznymi wstawkami HTML: shortcode jest wykonywany po stronie serwera. Przekazuje mu Pan/Pani parametry, a wynik jest generowany dynamicznie. Zmienia się treść, zmienia się wynik, bez ręcznego poprawiania dziesiątek stron.

Z perspektywy edytora jest pewien niuans. Edytor wizualny (Gutenberg lub klasyczny TinyMCE) natychmiast renderuje shortcode w podglądzie, dlatego do pracy z parametrami i zagnieżdżonymi znacznikami należy przełączyć się w tryb tekstowy. Tylko tam widać rzeczywistą strukturę: znacznik otwierający, atrybuty, zawartość, znacznik zamykający.

Wbudowane shortcode’y WordPressa: co jest dostępne bez wtyczek

WordPress jest dostarczany z sześcioma zarejestrowanymi shortcode’ami. Nie trzeba ich włączać ani konfigurować, po prostu wstawia się je do wpisu i otrzymuje wynik.

Najbardziej elastyczny z nich to [gallery]. Atrybut ids umożliwia wskazanie konkretnych obrazów po ID, nawet tych, które nie są dołączone do bieżącego wpisu. Atrybut size określa rozmiar miniatur (thumbnail, medium, large lub full). Połączenie tych dwóch parametrów pokrywa większość scenariuszy, dla których wcześniej instalowało się osobną wtyczkę galerii.

[audio] i [video] obsługują wiele źródeł, przeglądarka sama wybierze zgodny format. Playlisty przez [playlist] są tworzone z ID załączników analogicznie do galerii, ale wyświetlają odtwarzacz z przełączaniem utworów.

Parametry shortcode’ów: jak sterować wynikiem

Większość shortcode’ów przyjmuje atrybuty w formacie key="value". Podstawienie wartości zmienia logikę działania funkcji bez ingerencji w kod.

Weźmy [gallery]. Bez parametrów pokazuje on wszystkie obrazy wpisu w standardowym rozmiarze. Dodajemy konkrety:

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

Teraz wynik jest ograniczony do trzech wskazanych obrazów, rozmiar został zwiększony do large, a siatka ułożona w trzy kolumny. Parametry można dowolnie łączyć, a te niepodane otrzymują wartości domyślne.

Niektóre shortcode’y używają znacznika otwierającego i zamykającego, gdy między nimi trzeba przekazać zawartość. Na przykład wtyczka Google Maps może oczekiwać konstrukcji w rodzaju:

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

Znacznik zamykający zawsze zaczyna się od ukośnika /. WordPress używa tej notacji, aby odróżnić treść między znacznikami od atrybutów wewnątrz znacznika otwierającego.

Jak stworzyć własny shortcode

Kiedy dziesiąty raz w tygodniu wstawia Pan/Pani do artykułu ten sam adres URL, blok HTML lub wezwanie do działania, to najwyższy czas napisać shortcode. Nie wymaga to bycia programistą PHP: podstawowa konstrukcja mieści się w trzech linijkach.

Prosty shortcode dla URL

Proszę dodać ten kod na końcu pliku functions.php swojego motywu (Wygląd → Edytor motywu → functions.php):

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

Teraz w każdym wpisie [techblog] zostanie automatycznie zastąpiony adresem URL witryny. Funkcja zwraca ciąg znaków, a WordPress wstawia go w miejsce shortcode’a.

Dwie krytycznie ważne zasady z oficjalnej dokumentacji:

• Funkcja zwraca wartość przez return, a nie wypisuje przez echo. Bezpośrednie wypisywanie psuje kolejność renderowania i prowadzi do nieoczekiwanych rezultatów.
• Rejestruj shortcode’y na hooku init, aby WordPress zdążył załadować wszystkie zależności:

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

Shortcode do obrazka z konfigurowalnymi atrybutami

Nieco bardziej złożony scenariusz: chcą Państwo wstawiać obrazek, podając szerokość i wysokość bezpośrednio w edytorze. W pliku 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' );

Użycie w edytorze:

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

Funkcja shortcode_atts() łączy przekazane atrybuty z wartościami domyślnymi, to standardowy i bezpieczny sposób obsługi parametrów. Proszę zwrócić uwagę na esc_url() oraz esc_attr(): eskejpowanie jest obowiązkowe przy wyprowadzaniu danych wprowadzonych przez użytkownika na frontend. Pełna lista dostępnych atrybutów obrazka znajduje się w specyfikacji W3C.

Osobno warto wspomnieć o walidacji atrybutów. Gdy przyjmują Państwo wartości od redaktora i wstawiają je do HTML, zawsze należy sprawdzać typ danych. Dla atrybutów liczbowych takich jak width i height proszę używać intval(), to odetnie przypadkowe litery. Dla ciągów znaków proszę definiować dozwolony zestaw wartości przez in_array(), na przykład rozmiary miniaturek (thumbnail, medium, large). Dzięki temu układ pozostanie nienaruszony, a wynik na frontendzie będzie przewidywalny, nawet jeśli autor pomyli się w wartości atrybutu.

Shortcode’y w widżetach tekstowych i plikach PHP

Od wersji WordPress 4.9 (listopad 2017) shortcode’y automatycznie działają w widżetach tekstowych. Jeśli jednak używają Państwo niestandardowego motywu bez wbudowanej obsługi, można ją włączyć jednym wierszem w functions.php:

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

Aby uniknąć automatycznego wstawiania znaczników <p> i <br> wokół shortcode’a w widżecie (WordPress autoformatuje znaki nowej linii), proszę dodać również:

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

Ta sama zasada działa w szablonach PHP. Jeśli trzeba wykonać shortcode bezpośrednio w header.php lub innym pliku motywu, proszę opakować go w do_shortcode():

1
echo do_shortcode( '[techblog]' );

W ten sposób ta sama logika jest dostępna i w edytorze, i w widżecie, i w szablonie, bez duplikowania kodu.

Wyświetlanie: jak pokazać tekst shortcode’a bez jego wykonywania

Czasami trzeba nie wykonać shortcode’a, a pokazać jego składnię czytelnikowi, jak w tym artykule. Jeśli po prostu wstawi Pan [gallery] w edytorze, WordPress natychmiast go wykona lub pokaże placeholder. Są dwa sposoby, aby tego uniknąć.

Podwójne nawiasy kwadratowe. Najprostsza metoda, podwoić zewnętrzne nawiasy:

1
[[gallery]]

Dla tagów parzystych podwaja się pierwszy otwierający i ostatni zamykający:

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

Kody HTML znaków. W edytorze tekstowym można zastąpić nawiasy ich kodami ASCII: [ zamiast [ i ] zamiast ]. Zapis [gallery] wyświetli się jako tekst [gallery], ale nie zostanie wykonany.

Pierwszy sposób jest prostszy i czytelniejszy w kodzie źródłowym, drugi jest pewniejszy przy skomplikowanym formatowaniu. Proszę wybierać podwójne nawiasy do szybkich poprawek w edytorze tekstowym oraz kody ASCII, gdy shortcode sąsiaduje z innymi nawiasami kwadratowymi, na przykład wewnątrz bloków kodu lub opisów pól meta. W obu przypadkach odwiedzający witrynę widzi dokładnie tekst shortcode’a, a WordPress go nie wykonuje.

Wideo: pełna analiza shortcode’ów WordPress

Dla tych, którzy wolą wyjaśnienie wizualne, proszę bardzo, szczegółowy tutorial od zespołu Kinsta. Autor pokazuje tworzenie, debugowanie i rzeczywiste przykłady shortcode’ów w żywym projekcie, od instalacji motywu po wyświetlenie na frontendzie.

⁉️🤔 Często zadawane pytania

Czy można używać shortcode’ów w Gutenbergu?

Tak, poprzez blok „Shortcode" w panelu dodawania bloków. Wstawia Pan shortcode w pole bloku, a WordPress wykonuje go podczas renderowania. Jednak złożone shortcode’y z zagnieżdżoną treścią mogą działać nieprzewidywalnie, w takich przypadkach bezpieczniej jest przełączyć się w tryb edycji kodu. Gutenberg renderuje shortcode’y poprzez serwerowy callback, więc wynik zależy od tego, czy funkcja zwraca poprawny HTML. Motywy blokowe (Full Site Editing) z theme.json mogą częściowo ograniczać wyświetlanie shortcode’ów w szablonach, proszę sprawdzić kompatybilność konkretnego motywu.

Co zrobić, jeśli shortcode nie działa?

Proszę sprawdzić trzy typowe przyczyny. Po pierwsze: wstawił Pan shortcode w edytorze wizualnym, który zamienił nawiasy na encje HTML, proszę przełączyć się w tryb tekstowy i upewnić się, że nawiasy są proste. Po drugie: wtyczka rejestrująca shortcode jest dezaktywowana, proszę wejść w „Wtyczki" i sprawdzić status. Po trzecie: w funkcji shortcode’a użyto echo zamiast return, to błąd programisty, wynik pojawia się w niewłaściwym miejscu strony. Systemowy sposób diagnostyki: proszę otworzyć wp-config.php, włączyć WP_DEBUG i WP_DEBUG_LOG. Po załadowaniu strony z shortcode’em proszę sprawdzić wp-content/debug.log, znajdą się tam konkretne błędy PHP ze wskazaniem pliku i linii.

Czy można wstawić kod PHP bezpośrednio w shortcode?

Nie. Shortcode to wyzwalacz, a nie pojemnik na dowolny kod. Wykonywana jest funkcja zarejestrowana po stronie serwera przez add_shortcode(). Jeśli potrzebuje Pan niestandardowej logiki, proszę napisać ją w functions.php (lub w osobnej wtyczce) i powiązać z shortcode’em. Między nawiasami kwadratowymi można przekazywać tylko treść i atrybuty, a nie kod wykonywalny. Do bezpiecznego wykonywania PHP w treści proszę zapoznać się z wtyczkami typu „Code Snippets", umożliwiają one zarządzanie snippetami przez interfejs panelu administracyjnego bez edycji functions.php i z ochroną przed błędami krytycznymi.

Czy shortcode’y spowalniają witrynę?

Same w sobie nie. add_shortcode() jedynie rejestruje powiązanie tagu i funkcji w globalnej tablicy $shortcode_tags. Koszt pojawia się, gdy funkcja shortcode’a wykonuje ciężkie zapytania do bazy danych lub zewnętrznych API przy każdym ładowaniu strony. Problem nie leży w mechanizmie shortcode’ów, a w implementacji konkretnej wtyczki. Punkt odniesienia: jeśli strona zawiera ponad 20 shortcode’ów, z których każdy wywołuje WP_Query lub wp_remote_get(), proszę buforować wyniki za pomocą Transients API. Dla typowych scenariuszy (jeden-dwa shortcode’y na stronę) wpływ na wydajność jest pomijalnie mały.

Jak usunąć shortcode z wyświetlania, nie usuwając go z wpisu?

Proszę użyć remove_shortcode() w functions.php. Na przykład, aby wyłączyć wbudowaną galerię: remove_shortcode( 'gallery' ). Po tym [gallery] w tekście wpisu wyświetli się jako zwykły tekst w nawiasach kwadratowych, bez wykonywania. Przyda się to podczas migracji na inne rozwiązanie lub debugowania konfliktów. Częściowe wyłączenie: można nadpisać shortcode, rejestrując własną funkcję obsługi z tym samym tagiem przez add_shortcode(). Ostatnia zarejestrowana funkcja obsługi ma priorytet.

Czy warto uczyć się shortcode’ów w 2026 roku

Gutenberg i edytor blokowy rozwiązały wiele zadań, dla których wcześniej pisano shortcode’y: kolumny, przyciski, wstawianie mediów, opakowania. Ale shortcode’y nigdzie nie zniknęły. Wtyczki wciąż rejestrują ich setki, od formularzy subskrypcji po koszyki WooCommerce. A co najważniejsze, jeden niestandardowy shortcode może zastąpić wtyczkę i zrobić dokładnie to, czego potrzebuje Pana projekt, bez przeciążania panelu administracyjnego cudzymi ustawieniami.

Jeśli regularnie powtarza Pan w artykułach ten sam blok HTML, link lub szablon, proszę poświęcić 10 minut na add_shortcode() w functions.php. Zwrot z inwestycji: dziesiątki godzin rocznie, których nie traci Pan na kopiuj-wklej. Shortcode’y są wstecznie kompatybilne, napisany dziś kod będzie działał w kolejnych wersjach WordPressa, ponieważ API shortcode’ów nie zmieniło się od momentu powstania i pozostaje jednym z najstabilniejszych elementów rdzenia.