Theme Directory Structure & File Mapping

A SitePack theme follows a structured, standard directory layout. This directory conventions-based system ensures that the SitePack compilation engine can instantly locate, resolve, and render your templates, modular snippets, layouts, translations, and dynamic configurations.

By keeping the folder names consistent, SitePack can optimize asset delivery and inject the correct e-commerce data models depending on the page a customer is visiting.

High-Level Folder Hierarchy

When you initialize a theme using sitepack theme:init, the local project workspace is automatically hydrated with the following directory tree:

your-theme-directory/
├── assets/                  # Public frontend static resources
│   ├── css/                 # Pre-minified storefront CSS stylesheets
│   ├── js/                  # Frontend JavaScript scripts
│   └── img/                 # Theme images and static graphics
├── layouts/                 # Root wrapper shells (HTML structures)
│   └── base.twig            # The core base layout
├── snippets/                # Reusable template snippets (DRY blocks)
│   ├── header.twig          # Site-wide top header element
│   ├── footer.twig          # Site-wide bottom footer element
│   ├── product-card.twig    # Standard catalog item list-card
│   ├── blog-card.twig       # Article summary card (blog & tag listings)
│   └── category-card.twig   # Sub-category tile (category listing)
├── templates/               # Standard e-commerce view templates
│   ├── index.twig           # Homepage template
│   ├── product.twig         # Single product details template
│   ├── category.twig        # Category / Product list template
│   ├── cart.twig            # Shopping cart overview template
│   ├── account.twig         # Customer portal / Orders template
│   ├── page.twig            # Standard rich-text content page
│   ├── legal.twig           # Legal document page (Terms, Privacy, etc.)
│   ├── landing-page.twig    # Example custom template (see theme.json)
│   ├── blog.twig            # Article collection listing page
│   ├── article.twig         # Single blog post content template
│   ├── tag.twig             # Article listing filtered by tag
│   ├── sitemap.twig         # Human-readable HTML sitemap page
│   └── 404.twig             # Page Not Found template
├── translations/            # Multi-lingual locale definitions
│   ├── en.json              # English localization keys
│   └── nl.json              # Dutch localization keys
├── .sitepackignore          # Files/folders excluded from CLI sync
└── theme.json               # Mandatory theme manifest metadata

Detailed Directory Breakdowns

`/assets`

The assets directory contains all static client-side resources required to style and animate your theme.

/css: Contains .css files. SitePack does not compile SCSS/Sass or compress/minify CSS files on the fly. Developers must supply their final, completed build with pre-minified CSS directly inside this folder.
/js: Pure or compiled JavaScript files. Keep interactive logic (such as cart count updates or gallery sliders) structured here.
/img & /fonts: House your logos, background SVG vectors, fallback loaders, and web font formats (woff, woff2).
Note on Performance: All static assets are automatically edge-cached and globally distributed via the high-speed SitePack CDN during staging and production builds. They utilize automated URL hash-versioning to eliminate client-side caching delays. Read the full Assets Guide.

`/layouts`

Layouts act as the HTML boilerplate wrapper shells for your entire store.

base.twig: The main layout file that other templates extend. It contains structural outer HTML tags (<!DOCTYPE html>, <html>, <head>, <body>). It includes global headers, imports essential styles via helper functions (sitepack_head()), sets up analytics scripts, declares app injection blocks, and defines the content insertion region.
Template Extension: Storefront template files extend this base structure:
```
{% extends 'layouts/base.twig' %}
```

`/snippets`

Snippets are highly modular, self-contained template segments meant to be included in other layouts or pages. This keeps your codebase DRY (Don't Repeat Yourself) and highly maintainable.

header.twig: The main site navigation header snippet.
footer.twig: The site footer snippet.
product-card.twig: A single product list representation used on collection listings, search results, and recommended product carousels.
Inclusion Syntax: Reusable snippets are imported using Twig's include statement:
```
{% include 'snippets/product-card.twig' with { 'product': item } %}
```

`/templates`

The templates folder contains the specific view designs for each page type. Each template is loaded automatically by the SitePack routing engine when a customer visits the matching URL. SitePack injects context-specific data structures into these templates automatically:

File Name	Storefront Page	Primary Injected Objects & Context
`index.twig`	Homepage	`collections.frontpage.products` for the featured product grid.
`product.twig`	Single Product Details	The fully populated `product` object, plus `product_cross_sell` and `product_related` arrays.
`category.twig`	Collection / Category List	The current `category` object, an array of matching `products`, plus `sub_categories` and `quick_filters`.
`cart.twig`	Shopping Cart Overview	The `cart` object (totals, item count) — line-item markup itself is rendered by `sitepack_cart()`.
`account.twig`	Customer Profile & Orders	The `customer` object plus order history and saved addresses.
`page.twig`	Standard Content Pages	Rendered via `sitepack_content()` — no page-specific Twig variables needed.
`legal.twig`	Legal Documents (Terms, Privacy, etc.)	Rendered via `sitepack_content_legal()`.
`landing-page.twig`	Example Custom Template	Custom field values, exposed on the `page` object (see theme.json Reference).
`blog.twig`	Blog List View	The `blog` object: `blog.title`, `blog.articles`.
`article.twig`	Single Blog Article	The active `article` object: title, image, content, tags, author, publish date.
`tag.twig`	Articles Filtered by Tag	The `tag` object: `tag.title`, `tag.description`, `tag.blogs`.
`sitemap.twig`	Human-Readable Sitemap	The `sitemap` object: `pages`, `categories`, `products`, `blogs`.
`404.twig`	Page Not Found Error	No special context — just the standard globals (`site`, `navigation`, etc.).

For the full field-by-field breakdown of every object listed above, see the Twig Global Objects Guide.

`/translations`

SitePack themes support full multi-lingual localization.

Contains JSON translation dictionary files (e.g., en.json, nl.json, de.json).
Important Rule: File names MUST be written in lowercase, representing either the base language (en.json) or region-specific configurations (nl_be.json). SitePack utilizes an intelligent hierarchical resolution fallback during language lookup. Read the Translations Guide.

The Root Manifest: `theme.json`

The root of your theme workspace must always contain the theme.json manifest. This file acts as the registration registry for the SitePack compiler, detailing the theme's name, active version, author profile, custom schemas, and headless-like custom template blueprints. All Customizer settings and schemas are configured directly inside this file.

Now that you understand the directory layout of your theme, learn how to configure the root manifest in the theme.json Reference Guide!

High-Level Folder Hierarchy​

Detailed Directory Breakdowns​

/assets​

/layouts​

/snippets​

/templates​

/translations​

The Root Manifest: theme.json​