theme.json Şeması

theme.json, temanızın kimlik kartıdır. İçinde tema adı, sürüm, yazarı gibi bilgiler var; bir de özelleştiricide hangi seçeneklerin görüneceğini bu dosya belirler. Bir yerde bir şey ters giderse genelde buraya bakıp anlarız. Bu sayfa, içinde hangi alanların olabileceğinin tam listesini veriyor.

Üst düzey alanlar

| Alan | Tür | Zorunlu | Açıklama | |---|---|---|---| | name | string | evet | Admin panelde gösterilen insan okunabilir ad | | slug | string | evet | Klasör adıyla aynı olmak zorunda, küçük harf ve tire | | version | string | evet | Semver önerilir (1.0.0) | | author | string | evet | Yazar adı veya kurum | | description | string | hayır | Tema seçici için tek cümlelik özet | | license | "free" \| "premium" | hayır | "premium" yazarsanız aktif etmek için STD+ lisans şart | | requires | string | hayır | Minimum jekcms sürümü, örn. ">=2.0" | | preview | string | hayır | Önizleme görseline göreli yol (örn. "preview.jpg") | | settings | object | hayır | Eski usul varsayılan renk/font bloğu (aşağıda) | | customizer | object | hayır | Özelleştirici sekmeleri ve alanları |

Eski settings bloğu

settings.colors ve settings.typography eski usul. Hâlâ çalışıyor ama yeni temalar bunun yerine customizer.tabs kullanmalı — çünkü o, admin'in panelden düzenleyebileceği bir arayüz üretiyor; eskisi dosyaya sabitlenmiş değerler koyuyordu.

{
    "settings": {
        "colors": {
            "primary": "#2563eb",
            "text": "#0f172a",
            "background": "#ffffff"
        },
        "typography": {
            "body": "Inter, system-ui, sans-serif",
            "heading": "Inter, system-ui, sans-serif"
        }
    }
}

Şablon içinden bu değerlere theme_setting('colors.primary') ile ulaşırsınız.

customizer.tabs nasıl yapılandırılır?

customizer.tabs altındaki her anahtar bir sekmedir. Sekme anahtarları küçük harf, kısa ve tiresiz olmalı (theme_option('tab.field') ile çağırırken ilk segment olarak kullanılıyor).

{
    "customizer": {
        "tabs": {
            "branding": {
                "label": "Branding",
                "description": "Logo, colors, and voice.",
                "icon": "palette",
                "fields": { "...": "..." }
            }
        }
    }
}

Sekmenin kendi alanları

| Alan | Tür | Açıklama | |---|---|---| | label | string | Kenar çubuğunda gösterilen sekme başlığı | | description | string | Başlığın altındaki küçük yardımcı metin | | icon | string | Lucide ikon adı (palette, layout, type, code vb.) | | fields | object | Alan anahtarı → tanım eşlemesi |

Alan tipleri

Her alan nesnesi bazı ortak anahtarları ve tipine özgü anahtarları kabul eder.

Her tipte ortak olan anahtarlar

| Anahtar | Tür | Açıklama | |---|---|---| | type | string | Zorunlu. Şunlardan biri: color, font, range, toggle, select, textarea, code, url, text | | label | string | Kullanıcıya gösterilen alan adı | | default | değişken | Kullanıcı ayarlamadıysa varsayılan değer | | help | string | Girişin altında gösterilen ipucu | | css_var | string | Verirseniz, değer otomatik olarak :root içinde --ad: değer; diye yayınlanır |

Tipe özel anahtarlar

| Tip | Ek anahtarlar | Default biçimi | |---|---|---| | color | — | "#2563eb" | | font | — | {"family": "Inter", "weight": "400"} | | range | min, max, step, unit | Sayı (örn. 1200) | | toggle | — | true / false | | select | options ({"anahtar": "Etiket"}) | Seçim anahtarı | | textarea | rows | Dize | | code | language ("css", "html", "js") | Dize | | url | — | Dize | | text | maxlength | Dize |

Tam bir örnek

Üç sekmeli bir tema — branding, layout, advanced:

{
    "name": "Ocean",
    "slug": "ocean",
    "version": "1.0.0",
    "author": "jekcms Team",
    "description": "A clean coastal theme with a modern typographic scale.",
    "license": "free",
    "requires": ">=2.0",
    "preview": "preview.jpg",
    "customizer": {
        "tabs": {
            "branding": {
                "label": "Branding",
                "icon": "palette",
                "fields": {
                    "accent": {
                        "type": "color",
                        "label": "Accent color",
                        "default": "#0891b2",
                        "css_var": "--color-accent",
                        "help": "Used for links, buttons, and focus rings."
                    },
                    "body_font": {
                        "type": "font",
                        "label": "Body font",
                        "default": {"family": "Inter", "weight": "400"},
                        "css_var": "--font-body"
                    },
                    "logo": {
                        "type": "url",
                        "label": "Logo URL",
                        "default": ""
                    }
                }
            },
            "layout": {
                "label": "Layout",
                "icon": "layout",
                "fields": {
                    "max_width": {
                        "type": "range",
                        "label": "Content max width",
                        "default": 1200,
                        "min": 800,
                        "max": 1600,
                        "step": 40,
                        "unit": "px",
                        "css_var": "--layout-max-width"
                    },
                    "sidebar": {
                        "type": "select",
                        "label": "Sidebar position",
                        "default": "right",
                        "options": {
                            "left": "Left",
                            "right": "Right",
                            "none": "No sidebar"
                        }
                    },
                    "sticky_header": {
                        "type": "toggle",
                        "label": "Sticky header",
                        "default": true
                    }
                }
            },
            "advanced": {
                "label": "Advanced",
                "icon": "code",
                "fields": {
                    "custom_css": {
                        "type": "code",
                        "language": "css",
                        "label": "Custom CSS",
                        "default": ""
                    },
                    "head_html": {
                        "type": "textarea",
                        "label": "Custom <head> HTML",
                        "rows": 6,
                        "default": "",
                        "help": "Injected before </head>. Use for analytics or verification tags."
                    }
                }
            }
        }
    }
}

Değerlere şablon içinden theme_option('branding.accent'), theme_option('layout.max_width') gibi çağrılarla ulaşırsınız. css_var verdiğiniz alanlar için ise doğrudan CSS'te değişkeni kullanmanız yeterli — PHP fonksiyonuna gerek yok.