WordPress theme.json: settings, styles ve kademeli sıralama

theme.json, blok temanın kök dizininde duran ve birbirinden ayrı iki iş yapan tek bir yapılandırma dosyasıdır: settings blok editörünün kullanıcıya neler sunacağına, styles ise sitenin varsayılan olarak neye benzeyeceğine karar verir. WordPress bu dosyayı ayrıştırır, kendi varsayılanlarıyla ve Site Editor’da kaydedilmiş her şeyle birleştirir, sonucu da her sayfada CSS özel değişkenleri ve satır içi bir stil sayfası olarak çıktılar.

theme.json düzenlemelerinin çoğunun hiçbir işe yaramıyormuş gibi görünmesinin sebebi bu iki işi birbirine karıştırmaktır. settings altında bir renk tanımlamak o rengi hiçbir yere uygulamaz. Yalnızca bir değişken ve editör kenar çubuğunda bir renk kutucuğu oluşturur.

Üst düzey anahtarlar

En sade hâliyle dosya şöyle görünür:

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "settings": {},
  "styles": {},
  "templateParts": [],
  "customTemplates": []
}

Anahtar	Ne işe yarar
$schema	Yalnızca kod editöründe otomatik tamamlama ve doğrulama sağlar. WordPress bunu yok sayar.
version	WordPress’e hangi şema biçimini ayrıştıracağını söyler. Tema sürümünüz değildir.
settings	CSS değişkenleri üretir ve editörün neyi açtığını belirler.
styles	Gerçek varsayılan stilleri uygular.
templateParts	parts/ içindeki parçaları ve hangi alana ait olduklarını bildirir.
customTemplates	templates/ içindeki sayfa şablonlarını yazı editörüne kaydeder.

version insanları yanıltır, çünkü tema sürüm numarasına benziyor. Değildir. Bir ayrıştırma modu seçer ve eski WordPress sürümleri tanımadıkları bir şema biçimine ait anahtarları sessizce yok sayar. Eski kurulumları destekliyorsanız, yeni anahtarların sorunsuzca geri düşeceğini varsaymak yerine o kurulumların anladığı sürümü hedefleyin. Bu yazının yazıldığı tarihte güncel sürüm 3; sürüm 2 ise hâlâ yaygın olarak kullanılıyor ve hâlâ ayrıştırılıyor.

$schema, WordPress’in barındırdığı bir şema adresini işaret eder. trunk olarak sabitlemek kod editörünüzde en yeni ipuçlarını verir; bilinçli olarak eski bir şemada kalıyorsanız sürüme özel bir adres daha güvenlidir.

settings: editörün sunduğu şeyler

settings altındaki her şey bir CSS özel değişkeni ve çoğu durumda editörde bir kontrol üretir. settings altındaki hiçbir şey tek başına stil vermez.

{
  "settings": {
    "color": {
      "palette": [
        { "slug": "brand", "color": "#1f4ed8", "name": "Brand" },
        { "slug": "ink", "color": "#111827", "name": "Ink" }
      ],
      "custom": false
    },
    "typography": {
      "fontSizes": [
        { "slug": "small", "size": "0.875rem", "name": "Small" },
        { "slug": "large", "size": "1.5rem", "name": "Large" }
      ]
    },
    "layout": {
      "contentSize": "680px",
      "wideSize": "1200px"
    }
  }
}

Bu tanım, ön ayar yolundan ve slug değerinden türetilen değişkenler üretir:

--wp--preset--color--brand
--wp--preset--color--ink
--wp--preset--font-size--small
--wp--preset--font-size--large

Ayrıca .has-brand-color ve .has-brand-background-color gibi yardımcı sınıflar da üretir; editör seçilen bir rengi bloğa işte bu şekilde uygular.

"custom": false satırı ise settings işinin diğer yarısıdır: seçenekleri kapatmak. Bunu tanımladığınızda serbest renk seçici kaybolur ve kullanıcıya yalnızca sizin paletiniz kalır. Aynı kalıp her yerde geçerlidir — settings.typography.customFontSize, settings.spacing.customSpacingSize, settings.border ve devamı. settings altında süs olan hiçbir anahtar yoktur; her anahtar ya bir değişken ekler, ya bir kontrol ekler ya da bir kontrolü kaldırır.

settings.custom ise kendi değişkenleriniz için serbest biçimli bir kovadır:

{
  "settings": {
    "custom": {
      "lineHeight": { "body": 1.6 },
      "shadow": { "card": "0 1px 3px rgba(0,0,0,0.12)" }
    }
  }
}

Bunlar --wp--custom--line-height--body ve --wp--custom--shadow--card hâline gelir. Dönüşüme dikkat edin: camelCase anahtarlar kebab-case olarak bölünür ve iç içe geçmiş katmanlar çift tire ile birleştirilir. Bir değişken adını yanlış yazmak, bir değerin sessizce geri düşmesinin en sık sebeplerinden biridir.

Ayarları blok bazında da sınırlayabilirsiniz; düğmelerde renk seçiciye izin verip paragraflarda kapatmanın yolu budur:

{
  "settings": {
    "blocks": {
      "core/paragraph": {
        "color": { "custom": false, "customGradient": false }
      }
    }
  }
}

styles: gerçekten render edilen şey

Değerler styles içinde uygulanır. Yapısı editörün yapısını yansıtır: önce kök düzey, sonra elements, sonra blocks.

{
  "styles": {
    "color": {
      "background": "var(--wp--preset--color--base)",
      "text": "var(--wp--preset--color--ink)"
    },
    "typography": {
      "lineHeight": "var(--wp--custom--line-height--body)"
    },
    "elements": {
      "link": {
        "color": { "text": "var(--wp--preset--color--brand)" },
        ":hover": { "typography": { "textDecoration": "none" } }
      }
    },
    "blocks": {
      "core/quote": {
        "typography": { "fontStyle": "italic" },
        "spacing": { "padding": { "left": "var(--wp--preset--spacing--40)" } }
      }
    }
  }
}

Kök düzeydeki styles tanımları gövdeye iner. elements, blok olmayan HTML öğelerini kapsar — bağlantı, düğme, başlıklar, resim yazısı. blocks ise belirli bir blok türünü adıyla hedefler.

Dürüst sınır şu: styles, CSS’in ifade edebildiği her şeyi ifade edemez. Kendi medya sorgularınızı yazamazsınız, karmaşık seçici yoktur, animasyon yoktur ve yalnızca küçük bir sözde sınıf kümesi desteklenir. Akışkan tipografi ve yerleşime dayalı boyutlandırma, insanların kırılma noktalarıyla yaptığı işin çoğunu karşılar ama hepsini değil. Yayına çıkan blok temaların çoğu theme.json ile birlikte mütevazı bir stil sayfası taşır; bu bir başarısızlık değil, olağan bir sonuçtur.

settings ile styles tuzağı

Gelen destek sorularının en yaygını şunun bir versiyonudur: “Marka rengimi ekledim ama hiçbir şey değişmedi.”

Doğru. Rengi settings.color.palette içine eklemek --wp--preset--color--brand değişkenini ve bir renk kutucuğu oluşturdu. Hiçbir şey uygulamadı. Bunu varsayılan bağlantı rengi yapmak için styles altında da yazmanız gerekir:

{
  "settings": {
    "color": {
      "palette": [{ "slug": "brand", "color": "#1f4ed8", "name": "Brand" }]
    }
  },
  "styles": {
    "elements": {
      "link": { "color": { "text": "var(--wp--preset--color--brand)" } }
    }
  }
}

Şöyle okuyun: settings kullanıcıya uzattığınız boya kutusudur, styles ise o gelmeden önce duvara sürdüğünüz kattır.

Kademeli sıralama, en alttan en üste

Tema dosyasını “görmezden gelen” siteleri açıklayan kısım burasıdır. WordPress, CSS üretmeden önce birkaç katmanı birleştirir:

1. WordPress çekirdek varsayılanları — çekirdek, temel bir palet, yazı tipi boyutları ve boşluk ölçeği içeren kendi theme.json dosyasını taşır.
2. Ana temanın theme.json dosyası
3. Alt temanın theme.json dosyası — dosyanın tamamını değiştirmez, ana temanın üzerine anahtar anahtar birleşir.
4. Veritabanına kaydedilmiş Global Styles — Site Editor’daki Styles panelinin yazdığı kayıt.
5. Bloklara özel stiller — yazı içeriğinde saklanan ve satır içi stil ya da sınıf olarak render edilen nitelikler.

Siteleri bozan katman dördüncüsüdür. Biri Styles panelini açıp kaydettiği anda WordPress bir Global Styles kaydı oluşturur ve o kayıt, içerdiği her özellik için sizin dosyanızı yener. Sonrasında theme.json dosyasını düzenlemek o özellikler için görünür hiçbir şey değiştirmez; diskteki dosya bariz biçimde farklıyken site dağıtımdan sonra da tıpatıp aynı görünür.

Çözüm, !important ile bastırmak değil, kaydedilmiş kaydı temizlemektir. Site Editor’ı açın, Styles bölümüne gidin, revizyon panelini açın ve temanın varsayılanlarına dönün. Önce müşteriye ya da site sahibine danışın — sıfırlamak onların özelleştirmelerini siler; bu bedava bir işlem değil, gerçek bir kayıptır.

İkinci şüpheli önbelleklemedir. WordPress, her istekte dosyayı yeniden okumak yerine ayrıştırılmış theme.json verisini önbelleğe alır; bu üretimde tam olarak istediğiniz, geliştirme sırasında ise tam olarak istemediğiniz davranıştır. WP_DEBUG etkinleştirildiğinde ya da yeni sürümlerdeki tema geliştirme modu açıldığında WordPress dosyayı her seferinde yeniden okur. Düzenlemeleriniz yalnızca bir dağıtımdan veya önbellek temizliğinden sonra görünüyorsa, gördüğünüz şey budur.

templateParts ve customTemplates

İkisi de temanızda zaten duran dosyaları tarif eden dizilerdir.

{
  "templateParts": [
    { "name": "header", "title": "Header", "area": "header" },
    { "name": "footer", "title": "Footer", "area": "footer" }
  ],
  "customTemplates": [
    { "name": "page-wide", "title": "Wide Page", "postTypes": ["page"] }
  ]
}

name, uzantısı olmayan dosya adıyla eşleşir — parts/header.html, templates/page-wide.html. area değeri önemlidir: parçanın bir üst bilgi ya da alt bilgi işaret öğesiyle sarılıp sarılmayacağına ve editörün onu nasıl sınıflandıracağına karar verir. Bu değeri yazmazsanız parça sınıflandırılmamış sayılır.

Bir şablonun yazı editöründeki şablon açılır listesinde görünmesini sağlayan şey customTemplates girdisidir. Girdi yoksa dosya vardır ama kimse onu seçemez.

Hızlı bir teşhis sırası

Bir blok tema dosyanın söylediği gibi stil vermiyorsa, hiçbir şeye dokunmadan önce şu sırayı izleyin:

1. Kaynağı görüntüleyin ve üretilen global styles bloğunu arayın. Değişkeniniz orada yoksa sorun settings içindedir ya da slug yazımındadır.
2. Değişken var ama hiçbir yerde kullanılmıyorsa, sorun eksik bir styles girdisidir.
3. İkisi de varken bir şey onları eziyorsa, kaydedilmiş bir Global Styles kaydı olup olmadığına bakın.
4. Ancak bundan sonra kendi stil sayfanıza, eklentilere ya da kademeli sıralamanın sonuna CSS enjekte eden bir sayfa oluşturucuya bakın.