Theme Manifest & Settings Configuration (theme.json)

The theme.json file is the mandatory registration manifest located at the absolute root of your SitePack theme directory. It serves two vital architectural purposes:

1. Metadata Registration: It declares essential theme identity properties (such as name, version, description, and authorship) used by the SitePack compilation engine and displayed inside the SitePack Theme Marketplace.
2. Theme Configurator Engine Mapping: It acts as the central, unified configurator housing your interactive theme customizer settings as well as declaring advanced, headless-like custom template structures that merchants can safely customize without editing code. All customizer inputs are declared directly inside this single file.

---

The Root Manifest Structure

A standard theme.json blueprint contains the following root metadata and configuration fields:

{
  "name": "Summit Minimalist",
  "version": "1.2.0",
  "author": "CodeBrothers",
  "description": "An ultra-fast, minimalist e-commerce skin featuring a modern card-based collection layout.",
  "homepage": "https://codebrothers.eu/themes/summit-minimalist",
  "settings": [
    {
      "name": "Brand Color Schemes",
      "settings": [
        {
          "type": "color",
          "id": "primary_color",
          "label": "Primary Accent Color",
          "default": "#ff5500"
        },
        {
          "type": "color",
          "id": "bg_color_body",
          "label": "Body Background Color",
          "default": "#ffffff"
        }
      ]
    }
  ]
}

Root Metadata Fields Detailed

• name (string, required): The display name of your theme. This is shown in the merchant's active admin dashboard and as the primary title in the public theme directory.
• version (string, required): The active theme version. You must use strict Semantic Versioning conventions (e.g., 1.0.0, 1.2.3-beta). When you run sitepack theme:publish, version bumps are validated to manage caching and client updates.
• author (string, required): The individual developer name or company/agency brand owning the theme.
• description (string, required): A concise marketing summary outlining the theme's core aesthetics, ideal niches, and structural layouts.
• homepage (string, optional): A web URL linking to your developer portfolio, live theme demo, or customized documentation page.

---

Defining Customizer Settings ("settings")

The "settings" array dictates the customizer fields that appear inside the interactive SitePack Theme Editor. This is where you configure elements like colors, typography, toggles, and dropdown selectors that allow merchants to align the storefront skin with their brand guidelines.

The structure consists of an array of setting categories (groups), where each category contains an array of individual field definitions.

Supported Customizer Setting Field Types

When building your settings array inside theme.json, you can use the following supported inputs:

Input Type	Description / Usage	Output Value in Twig
color	Color picker popup returning standard Hex value strings.	Hex code string (e.g., #ff5500).
font	Dropdown list of pre-vetted Google and system web fonts.	Complete CSS font family stack string.
text	Standard single-line input text field.	Raw string.
textarea	Large multi-line text input field for descriptions/paragraphs.	Raw string.
image	Image upload asset selector, feeding via SitePack CDN.	Full edge CDN image URL string.
boolean / checkbox	An on/off binary toggle switch.	Boolean true or false.
select	Custom dropdown select box with user-defined choices.	The value string of the chosen option.

Complete "settings" Block Example

{
  "name": "Summit Minimalist",
  "version": "1.2.0",
  "author": "CodeBrothers",
  "description": "An ultra-fast, minimalist e-commerce skin.",
  "settings": [
    {
      "name": "Brand Color Schemes",
      "settings": [
        {
          "type": "color",
          "id": "primary_color",
          "label": "Primary Accent Color",
          "default": "#ff5500"
        },
        {
          "type": "color",
          "id": "bg_color_body",
          "label": "Body Background Color",
          "default": "#ffffff"
        },
        {
          "type": "color",
          "id": "text_color_body",
          "label": "Body Text Color",
          "default": "#333333"
        }
      ]
    },
    {
      "name": "Storefront Typography",
      "settings": [
        {
          "type": "font",
          "id": "base_font_family",
          "label": "Primary Font Family",
          "default": "Open Sans, sans-serif"
        }
      ]
    },
    {
      "name": "Homepage Configuration",
      "settings": [
        {
          "type": "boolean",
          "id": "show_hero_banner",
          "label": "Enable Top Hero Banner",
          "default": true
        }
      ]
    }
  ]
}

Accessing Customizer Settings inside Twig

Once a merchant configures values through the Theme Editor, SitePack compiles them and exposes them inside all your Twig templates via the global settings object.

You can render or hook these properties directly into stylesheets or conditional blocks:

{# Inject customizer colors and typography variables dynamically in layouts/base.twig #}
<style>
  :root {
    --primary-color: {{ settings.primary_color }};
    --bg-color: {{ settings.bg_color_body }};
    --text-color: {{ settings.text_color_body }};
    --base-font: {{ settings.base_font_family }};
  }
  
  body {
    background-color: var(--bg-color);
    color: var(--text-color);
    font-family: var(--base-font);
  }
</style>

{# Conditional rendering using boolean settings #}
{% if settings.show_hero_banner %}
  {% include 'snippets/homepage-hero.twig' %}
{% endif %}

---

Headless-Style Custom Layout Templates

SitePack themes support defining custom templates directly within the theme.json manifest.

Why Use Custom Templates? (The Headless Paradigm)

Instead of forcing merchants to navigate complex, fragile drag-and-drop page builders that often result in broken grid layouts and inconsistent margins, SitePack custom templates follow a structured-content model.

Designers pre-define the code structure and styling inside a standard Twig template. Then, you declare the inputs (the content fields) inside theme.json. Merchants simply fill in the structured input fields (e.g., typing titles, uploading images) in the editor, and SitePack safely merges their content with your bulletproof template design.

Custom Templates Manifest Configuration

To declare custom layouts, append a top-level "templates" array to your theme.json manifest:

{
  "name": "Summit Minimalist",
  "version": "1.2.0",
  "author": "CodeBrothers",
  "description": "An ultra-fast, minimalist e-commerce skin.",
  "settings": [
    {
      "name": "Brand Color Schemes",
      "settings": [
        {
          "type": "color",
          "id": "primary_color",
          "label": "Primary Accent Color",
          "default": "#ff5500"
        }
      ]
    }
  ],
  "templates": [
    {
      "key": "promo-landing-page",
      "name": "Promotional Landing Page",
      "fields": [
        {
          "key": "hero-title",
          "type": "text",
          "label": "Hero Title Heading"
        },
        {
          "key": "hero-sub-head",
          "type": "text",
          "label": "Hero Sub-Heading"
        },
        {
          "key": "hero-sub-paragraph",
          "type": "textarea",
          "label": "Hero Paragraph Description"
        },
        {
          "key": "hero-image",
          "type": "image",
          "label": "Hero Background Image Banner"
        },
        {
          "key": "features-list",
          "type": "list",
          "label": "List of core features (USPs)"
        }
      ]
    }
  ]
}

Template Registration Properties

Each template defined in the array is configured using these primary fields:

• key (string, required): The unique alphanumeric identifier for the custom template (e.g., "promo-landing-page"). This must directly match the filename of your Twig file in your templates folder: templates/{key}.twig (e.g., templates/promo-landing-page.twig).
• name (string, required): The human-friendly display label that content managers and merchants select from a template dropdown menu inside the SitePack Admin.
• fields (array, required): The collection of content-entry fields made available to merchants editing a page that uses this template.

Field Entry Schema Properties

Each field object inside the "fields" array consists of:

• key (string, required): The unique lookup identifier for the field (e.g., "hero-title"). This key is used to fetch the field data in your Twig file.
• type (string, required): The input type rendered in the administrator editor. Supported types are:
  • text: Standard text line.
  • textarea: Larger text block.
  • image: Media gallery upload field.
  • list: Interactive checklist array (ideal for adding bullet items or store benefits).
• label (string, required): Descriptive text displayed next to the customizer field in the Admin (e.g., "Hero Title Heading").

---

Accessing Custom Template Fields inside Twig

When a merchant applies a custom template to a page and fills out the fields, SitePack injects those configurations directly into your matching template Twig file as a unified fields object.

You can render any custom field dynamically using standard dot-notation, or bracket notation (which is mandatory if your keys contain hyphens like "hero-title").

Here is how you would program the corresponding template file templates/promo-landing-page.twig:

{% extends 'layouts/base.twig' %}

{% block content %}
    <header class="promo-hero-wrapper" style="background-image: url('{{ fields['hero-image'] }}');">
        <div class="promo-container">
            {# Safely render title - fall back to page title if custom title is empty #}
            <h1 class="promo-title">
                {{ fields['hero-title'] | default(page.title) }}
            </h1>
            
            {% if fields['hero-sub-head'] %}
                <h2 class="promo-subheading">{{ fields['hero-sub-head'] }}</h2>
            {% endif %}
            
            {% if fields['hero-sub-paragraph'] %}
                <p class="promo-description">{{ fields['hero-sub-paragraph'] }}</p>
            {% endif %}
        </div>
    </header>

    {% if fields['features-list'] is iterable and fields['features-list']|length > 0 %}
        <section class="promo-features-section">
            <div class="container">
                <h3 class="section-title">Why Shop With Us?</h3>
                <ul class="usp-checkmark-list">
                    {% for feature in fields['features-list'] %}
                        <li class="usp-item">{{ feature }}</li>
                    {% endfor %}
                </ul>
            </div>
        </section>
    {% endif %}
{% endblock %}

---

Exploring Further:

Now that you have configured your manifest and inputs, understand how static assets are served via the high-speed CDN in the Theme Assets Guide!