Jak tworzyć child theme w WordPress

Tworzenie motywu potomnego to najbezpieczniejszy sposób na modyfikowanie wyglądu i działania witryny opartej na WordPress, bez ryzyka utraty zmian przy aktualizacjach motywu głównego. W tym praktycznym przewodniku przejdziesz przez pełny proces: od przygotowania środowiska, przez utworzenie plików i włączenie stylów, po zaawansowane techniki nadpisywania szablonów, integracji z edytorem blokowym oraz utrzymania i wersjonowania. Każdy krok opisany jest możliwie konkretnie, z gotowymi fragmentami do skopiowania i checklistami.

Przygotowanie i fundamenty pracy z motywem potomnym

Co to jest motyw potomny i dlaczego warto

Motyw potomny to osobny katalog w themes/, który korzysta z zasobów motywu nadrzędnego, a Twoje zmiany nadpisują tylko wybrane elementy. Dzięki temu zyskujesz elastyczne dziedziczenie i bezpieczeństwo aktualizacji: rodzic może otrzymywać nowe funkcje i poprawki, a Twoje dopasowania pozostają nietknięte. To rozwiązanie jest standardem w świecie WordPress i zalecane przez twórców platformy.

Kiedy używać child theme, a kiedy alternatyw

Motyw potomny stosuj, gdy:

• Chcesz zmienić układ, części szablonów, style lub rejestrować dodatkowe funkcje.
• Plan modyfikacji wykracza poza kilka reguł w Personalizacji czy CSS dodatkowym.
• Motyw bazowy będzie regularnie aktualizowany i chcesz zachować kompatybilność.

Alternatywy mają sens, gdy: zmiany są minimalne (wówczas wystarczy CSS w panelu), modyfikujesz tylko funkcje niezwiązane z tematyką (rozważ wtyczkę funkcyjną), albo budujesz od zera motyw własny (zamiast potomnego).

Wymagania i narzędzia

• Dostęp do plików serwera: SFTP/FTP lub panel hostingu z menedżerem plików.
• Edytor tekstu (np. VS Code, Sublime Text) z podświetlaniem PHP/JSON/CSS.
• Znajomość podstaw CSS, HTML, a w stopniu minimalnym PHP. Przy motywach blokowych – JSON.
• Opcjonalnie: Git do wersjonowania, środowisko lokalne (np. Local, DDEV, Docker).

Struktura katalogów i nazewnictwo

Standardowa ścieżka motywów: wp-content/themes/. Wewnątrz znajdziesz katalog motywu nadrzędnego, np. twentytwentyfour. Utwórz obok katalog dziecka: twentytwentyfour-child (bez spacji, małe litery i myślniki). Unikaj polskich znaków i znaków specjalnych.

• Przykład: wp-content/themes/parent-theme/ oraz wp-content/themes/parent-theme-child/
• Nazwa Template w pliku style.css dziecka musi dokładnie odpowiadać nazwie katalogu rodzica.

Motywy klasyczne vs motywy blokowe (FSE)

W motywach klasycznych kluczowa jest hierarchia plików PHP (single.php, page.php itd.) i ręczne dołączanie stylów oraz skryptów. W motywach blokowych główne miejsce konfiguracji stanowi theme.json, a szablony znajdują się w katalogach templates/ i parts/. Child theme działa w obu światach, jednak różni się zakresem typowych modyfikacji.

Utworzenie motywu potomnego: pliki, aktywacja, style

Założenie katalogu i minimalne pliki

W katalogu wp-content/themes/ utwórz folder: nazwa-rodzica-child. Wewnątrz dodaj co najmniej style.css z nagłówkiem oraz (zwykle) functions.php. Pamiętaj, aby nie dodawać w tym katalogu elementów, które nie są związane z motywem.

Nagłówek style.css – wymagane metadane

Utwórz plik style.css i wklej nagłówek (pierwszy blok komentarza w pliku). Wartości zmień na własne:

/*
Theme Name: Parent Theme Child
Theme URI: https://twojadomena.pl/
Author: Twoje Imię
Author URI: https://twojadomena.pl/
Template: parent-theme
Description: Motyw potomny dla Parent Theme.
Version: 1.0.0
Text Domain: parent-theme-child
*/

Pozycja Template musi odpowiadać nazwie katalogu motywu nadrzędnego. Theme Name to nazwa przyjazna użytkownikowi – pojawi się w Kokpicie.

Ładowanie stylów bez @import – prawidłowe enqueue

Nie używaj @import w style.css – to nieefektywne i niezalecane. Zamiast tego dołącz style rodzica i dziecka w functions.php poprzez enqueue. W pliku functions.php (zaczynaj od <?php) dodaj:

add_action(’wp_enqueue_scripts’, function () {
wp_enqueue_style(’parent-style’, get_template_directory_uri() . '/style.css’);
wp_enqueue_style(
'child-style’,
get_stylesheet_uri(),
array(’parent-style’),
wp_get_theme()->get(’Version’)
);
}, 20);

W niektórych motywach rodzic ładuje główny CSS z innej ścieżki (np. assets/css/main.css). Sprawdź w functions.php rodzica lub w kodzie źródłowym strony (Network/Źródło) jaką ścieżkę wykorzystuje i zarejestruj właściwy plik. Jeśli rodzic rejestruje styl pod własną nazwą uchwytu (np. theme-style), możesz zamiast powyższego użyć go jako zależności dziecka.

Jeśli chcesz dodać dodatkowe pliki CSS/JS, rejestruj je również przez wp_enqueue_scripts i definiuj zależności tak, by najpierw ładował się styl rodzica, potem styl dziecka.

Aktywacja motywu potomnego w Kokpicie

• Wejdź w Wygląd → Motywy.
• Powinieneś zobaczyć nowy motyw o nazwie z Theme Name. Kliknij Aktywuj.
• Jeśli motyw się nie pojawia, sprawdź poprawność nagłówka style.css (Template). Gdy rodzic nie jest zainstalowany – najpierw go doinstaluj.

Plik screenshot.png oraz inne zasoby

W katalogu dziecka możesz dodać screenshot.png (ok. 1200×900 px), który będzie miniaturą w Kokpicie. Dodatkowo twórz podkatalogi na zasoby: assets/css/, assets/js/, assets/images/. Zachowuj konwencję nazewnictwa i porządek, co ułatwi utrzymanie.

Prawidłowe ładowanie funkcji – kolejność i najlepsze praktyki

WordPress ładuje functions.php rodzica, a następnie dziecka. To oznacza, że możesz w dziecku korzystać z funkcji i stałych zdefiniowanych przez rodzica. Jeśli musisz zmienić zachowanie, użyj akcji/filtrów i priorytetów, ewentualnie remove_action/remove_filter. Unikaj redefiniowania istniejących funkcji o tej samej nazwie.

Nadpisywanie szablonów, hierarchia, style i zasoby

Jak działa hierarchia szablonów

Gdy WordPress renderuje stronę, szuka najpierw pliku w motywie potomnym, a dopiero potem w rodzicu. Przykładowo: dla wpisu szuka single-{post-type}.php → single.php → singular.php → index.php. Wystarczy skopiować z motywu nadrzędnego plik, który chcesz zmodyfikować, do dziecka, zachowując identyczną ścieżkę i nazwę.

• Przykład: aby zmienić wygląd strony kategorii, skopiuj category.php lub utwórz category-slug.php.
• Aby zmienić stopkę, nadpisz footer.php; dla nagłówka – header.php.
• Dla archiwów taksonomii: taxonomy-{taxonomy}.php, taxonomy-{taxonomy}-{term}.php.

Motywy blokowe: templates/ i parts/ oraz theme.json

W motywach blokowych nadpisania wykonujesz, tworząc pliki w katalogach templates/ i parts/ w motywie potomnym. Np. templates/single.html nadpisze szablon pojedynczego wpisu, a parts/header.html – część nagłówka. Dodatkowo możesz stworzyć theme.json w dziecku – ustawienia i style z dziecka łączą się z rodzicem (dziecko nadpisuje wartości).

Przykładowy fragment theme.json dziecka (tekstowo):

{
„version”: 2,
„settings”: { „color”: { „palette”: [ { „name”: „Akcent”, „slug”: „accent”, „color”: „#0ea5e9” } ] } },
„styles”: { „typography”: { „fontSize”: „18px” } }
}

Dzięki temu możesz globalnie sterować kolorami, spacingiem, typografią, stylami bloków i zachowaniem szablonów. To wygodne, gdy nie chcesz dodawać nadmiarowego CSS.

Nadpisywanie plików WooCommerce i innych wtyczek

Jeśli motyw (rodzic) integruje się z WooCommerce (lub inną wtyczką), zwykle szablony leżą w parent/woocommerce/. Aby je nadpisać, skopiuj odpowiedni plik do child/woocommerce/ w tej samej strukturze. Sprawdzaj zgodność z wersjami WooCommerce – po aktualizacji wtyczka oznacza szablony jako nieaktualne, co wymaga przeglądu zmian.

Stylowanie i organizacja CSS/SCSS

Oprócz pliku style.css możesz utrzymywać modularny CSS w assets/css/ i kompilować SCSS do jednego pliku produkcyjnego. Dołączaj go przez wp_enqueue_style z zależnością od parent-style. Drobne modyfikacje dodawaj w style.css dziecka; większe – w osobnych plikach. Pamiętaj o specyficzności selektorów i kaskadzie – style dziecka ładują się po rodzicu.

Jeśli motyw rodzica używa CSS variables (custom properties) lub theme.json, preferuj dopasowanie tych mechanizmów zamiast agresywnego nadpisywania klas. To ułatwia utrzymanie i redukuje konflikt z aktualizacjami.

Skrypty JS i zależności

Skrypty JS dołączaj wp_enqueue_script z właściwymi zależnościami (np. wp-element, jquery – tylko jeśli niezbędne) i w trybie footera. Jeżeli rodzic rejestruje własny skrypt, możesz go zastąpić, deregisterować lub nadpisać wersją z dziecka, ale rób to świadomie, bo ryzykujesz niekompatybilność. Testuj w narzędziach deweloperskich przeglądarki.

Ładowanie tłumaczeń

W functions.php dodaj load_child_theme_textdomain(’parent-theme-child’, get_stylesheet_directory() . '/languages’). Dzięki temu pliki .po/.mo z katalogu languages/ w dziecku będą używane do tłumaczeń. Pamiętaj, aby w swoich funkcjach używać tego samego text domain, co w nagłówku style.css.

Porządek, standardy i kontrola jakości

• Przestrzegaj PSR-12 dla PHP i stylów kodu w CSS/JS.
• Nazywaj uchwyty stylów i skryptów jednoznacznie (np. theme-child-style, theme-child-app).
• Unikaj kopiowania niepotrzebnych plików z rodzica; nadpisuj tylko to, co zmieniasz.

Zaawansowane techniki, utrzymanie i narzędzia

Praca z akcjami i filtrami

Najczystsza metoda modyfikacji to akcje i filtry, czyli hooki. Zamiast kopiować cały szablon dla drobnej zmiany, sprawdź, czy istnieje odpowiedni filtr. Przykłady:

• add_filter(’excerpt_length’, function($l){ return 30; }); – zmiana długości zajawki.
• remove_action(’wp_head’, 'wp_generator’); – usunięcie metadanych z nagłówka.
• add_filter(’body_class’, function($classes){ $classes[]=’my-child’; return $classes; });

Pamiętaj o priorytetach (ostatni parametr add_action/add_filter). Dzięki nim możesz wykonywać kod po rodzicu, bez bezpośredniej ingerencji w jego pliki.

Motywy blokowe: wzorce, style i theme.json w praktyce

• Dodawaj własne patterns (wzorce bloków) w katalogu patterns/ i rejestruj je w PHP lub poprzez nagłówki wewnątrz plików.
• Warstwa theme.json w dziecku nadpisuje i rozszerza konfigurację rodzica. Korzystaj z sekcji settings i styles – to czystsze niż CSS.
• Jeżeli chcesz ograniczyć liczbę dostępnych bloków lub opcji, ustaw to w settings (np. disallowedBlocks, kontrola kolorów, spacing).

Wydajność: minimalizacja, ładowanie warunkowe, critical CSS

Staraj się ograniczać liczbę plików i wagi zasobów. Ładuj skrypty warunkowo, np. tylko na stronach, gdzie są potrzebne (is_page(), is_single()). Rozważ generowanie critical CSS dla above-the-fold i lazy-loading obrazów. Jeżeli wprowadzasz frameworki CSS/JS, upewnij się, że nie dublujesz ich z tym, co ładuje rodzic.

Kompatybilność i kontrola regresji

Po każdej aktualizacji motywu nadrzędnego uruchom testy wizualne i funkcjonalne. Sprawdzaj konsolę JS oraz logi PHP (WP_DEBUG_LOG). Dla WooCommerce porównuj szablony (stempel wersji w komentarzach). Trzymaj spis nadpisanych plików, aby wiedzieć, co trzeba sprawdzić po update.

Bezpieczeństwo i higiena kodu

Dodając własne funkcje, weryfikuj dane (sanitize_text_field, esc_html, wp_nonce_field). Nigdy nie wyłączaj mechanizmów bezpieczeństwa rodzica bez uzasadnienia. Używaj minimalnych uprawnień, nie przechowuj haseł w repozytorium i regularnie aktualizuj zależności. Świadome bezpieczeństwo jest równie ważne jak estetyka.

Aktualizacje, wersjonowanie, migracje

Utrzymuj wersję w style.css – podbijaj numer przy istotnych zmianach. Stosuj Git do śledzenia różnic i integruj z CI/CD, jeśli to projekt produkcyjny. Migracje pomiędzy środowiskami wykonuj przez pakiety zip lub Git; synchronizuj media i bazę narzędziami WP-CLI lub dedykowanymi wtyczkami. Nie zapominaj o regularnych kopiach zapasowych – sprawne aktualizacje wymagają planu B.

Przykładowe scenariusze i wzorce rozwiązań

• Nadpisanie tylko CSS: zostaw szablony bez zmian, w dziecku dodaj style i ewentualnie theme.json (motyw blokowy).
• Zmiana struktury wpisu: utwórz single.php w dziecku; jeśli to motyw blokowy – templates/single.html i odpowiednie parts/.
• Dodanie pola pod tytułem: skorzystaj z hooków (np. the_content, loop_start) zamiast kopiować cały plik.

Typowe problemy i ich diagnoza

• Motyw dziecka nie widoczny w Kokpicie: sprawdź nagłówek style.css, pozycję Template oraz uprawnienia plików.
• Style rodzica się nie ładują: zweryfikuj ścieżkę w wp_enqueue_style i kolejność wywołania.
• Konflikty JS: wyłączaj moduły etapami, obserwuj konsolę, użyj trybu bezpiecznego, testuj na czystym profilu przeglądarki.
• Szablon nie nadpisuje: czy nazwa i lokalizacja są identyczne jak w rodzicu? Sprawdź hierarchię szablonów.

WP-CLI i automatyzacja

WP-CLI ułatwia prace administracyjne: aktywację motywu (wp theme activate parent-theme-child), sprawdzanie dostępnych aktualizacji, wymianę adresów URL przy migracjach (wp search-replace). Połącz to z skryptami bash lub narzędziami CI, by automatyzować wdrożenia.

Struktura i konwencje w dziecku – przykład porządkowy

parent-theme-child/
├─ style.css
├─ functions.php
├─ screenshot.png
├─ assets/
│ ├─ css/
│ ├─ js/
│ └─ images/
├─ templates/ (motywy blokowe)
├─ parts/ (motywy blokowe)
├─ woocommerce/ (jeśli nadpisujesz szablony Woo)
└─ languages/

Rady końcowe dotyczące stabilności

• Zmiany rób iteracyjnie i często testuj. Jeden commit – jedna logiczna zmiana.
• Dokumentuj: notuj, co i dlaczego nadpisałeś. Przyspieszy to aktualizacje i onboarding.
• Preferuj rozszerzanie przez filtry/akcje zamiast kopiowania dużych plików szablonów.

Lista kontrolna: gotowość do publikacji

• style.css zawiera poprawny nagłówek i minimalny CSS.
• functions.php poprawnie ładuje style rodzica i dziecka; bez @import.
• Szablony nadpisane tylko tam, gdzie to potrzebne; nazwy i ścieżki zgodne.
• Brak błędów w konsoli JS i logu PHP; włączone WP_DEBUG w środowisku testowym.
• Backup wykonany; zmiany zmergowane i otagowane w repozytorium.

Najczęściej zadawane pytania

• Czy mogę stworzyć motyw potomny bez functions.php? Tak, ale wtedy style rodzica mogą się nie załadować. Lepiej dodać minimalny plik.
• Czy @import w style.css jest akceptowalny? Działa, ale jest niezalecany ze względów wydajności i kolejności ładowania.
• Czy nadpiszę funkcje rodzica? Nie bezpośrednio – lepiej użyć filtrów/akcji lub funkcji pluggable z warunkami function_exists.
• Motyw blokowy: lepiej theme.json czy CSS? W pierwszej kolejności theme.json i style bloków; CSS – gdy to konieczne.

Przykładowy minimalny zestaw zmian

Pliki:

• style.css – nagłówek + kilka reguł, np.: .site-title { letter-spacing: 0.02em; }
• functions.php – enqueue parent i child style + ewentualny mały filtr.
• templates/single.html lub single.php – drobna korekta układu treści.

Dzięki temu uzyskasz kontrolę nad wyglądem i funkcjonalnością bez naruszenia plików motywu nadrzędnego.

Słowa kluczowe do zapamiętania

W codziennej pracy z motywem dziecka najczęściej będziesz spotykać pojęcia: style.css, functions.php, enqueue, stylów, potomny. Do tego dochodzą aspekty utrzymania: bezpieczeństwo, aktualizacje i oczywiście samo WordPress z ideą dziedziczenie. Zrozumienie ich znaczenia pozwala tworzyć elastyczne i odporne na zmiany rozwiązania.