Theme Structure

A Finqu theme is organized into a set of well-defined directories, each serving a specific purpose. Understanding this structure is essential for developing, customizing, and maintaining themes efficiently.

Directory Overview

The typical theme directory contains the following folders:

Directory	Purpose
`assets`	Contains images, stylesheets, JavaScript files, and other static assets. Special handling is provided for `.liquid` and Sass files.
`blocks`	Reusable components that can be added to sections. Blocks can have their own settings and are designed for modularity.
`config`	Stores theme configuration files, including `settings_schema.json` (settings schema) and `settings_data.json` (actual settings).
`layout`	Contains layout files such as `theme.liquid`. Layouts define the overall structure of pages.
`locales`	Holds translation files for different languages. Each locale is a JSON file, e.g., `en.json`.
`public`	Publicly accessible files. All files here can be accessed directly via a browser.
`section-groups`	JSON definitions for shared section regions (e.g., `header-group.json`). Sections in a group are stored once and rendered wherever the group is included. See Sections.
`sections`	Defines page-level building blocks. Sections can contain blocks and are the main structural elements of a theme.
`snippets`	Small reusable code fragments. Snippets are rendered in their own context and can be included in templates.
`templates`	Page templates for different store pages (e.g., `frontpage.liquid`, `cart.liquid`).

Required Files and Folders

layout/theme.liquid: The main layout file. Additional layouts can be defined as needed.
config/settings_schema.json and config/settings_data.json: Define and store theme settings.
At least one template in the templates directory (e.g., frontpage.liquid).
Locale file for each supported language in locales (e.g., en.json).

Optional Components

Blocks: Modular components for use within sections. Useful for creating dynamic, customizable content areas.
Section groups: Shared, merchant-managed section regions (header, footer) that appear across multiple templates. Defined in section-groups/ and rendered with the {% sections %} tag.
Snippets: Reusable code pieces for icons, widgets, or other small features.
Additional layouts: For special page types (e.g., campaign.liquid).

Configuration Files

settings_schema.json: Defines the structure and available options for theme settings.
settings_data.json: Stores the actual values for the theme settings and presets.
config/.data/ (optional): Used by the Finqu designer to store merchant draft edits. Theme authors normally do not edit this directory.

Locale files

Each supported language needs a JSON file in locales/ (e.g. en.json, fi.json) for storefront strings used in your Liquid templates.

Schema translations: Add locales/{lang}.schema.json to translate section, block, and setting labels shown in the theme designer — without mixing them into storefront copy. Labels from .schema.json are merged into the corresponding locale at runtime.

See Localization for details.

Deploy lifecycle

Develop locally — Edit theme files in your project; preview with Theme Development Kit.
Deploy — Run finqu theme deploy or publish from the partner portal. Finqu compiles .scss.liquid assets into public/ on the merchant store.
Customize — Merchants edit sections and settings in the admin designer; changes are draft until published.

Your theme repo is the source of truth. After deploy, merchants customize via settings_data.json on the store — not by editing your repo directly.

Best Practices

Use the assets directory for all static files. Sass files are compiled with Dart Sass, and .liquid files are processed and cachebusted automatically.
Reference assets using the asset_url filter: {{ 'my_file.svg' | asset_url }}.
Organize blocks and sections for maximum reusability and maintainability.
Use the translation system in locales to support multiple languages and dynamic content.
Keep configuration files up to date and well-documented.