Guide: Liquid Templates & Theme Folder Structure (8 Fixed Folders)

Liquid templates control the presentation layer of your site — the layouts, sections, and small UI pieces that render your modules and routes.
This guide explains the exact 8 fixed folders, what each folder holds, how templates sync with routes, and how to structure themes so they work reliably in the system.

Folder tree (exact — 8 fixed folders)

theme/

│

├── assets/ → CSS, JavaScript, fonts, and images

├── config/ → Theme settings and configuration files

├── layout/ → Global layout files (site skeleton: header, footer, wrappers)

├── locales/ → Language / translation files

├── sections/ → Page-level, configurable sections (hero, product list)

├── blocks/ → Small modular blocks used inside sections (cards, badges)

├── snippets/ → Tiny reusable partials (buttons, icons, form fields)

└── templates/ → Page templates mapped to routes (liquid + JSON templates)

Note: This exact eight-folder layout must be followed. Missing or misnamed folders can break theme rendering and route-syncing.

Quick folder purposes (summary)

Blocks vs Sections vs Snippets — when to use which

• Sections

  • Big, configurable page areas. Examples: hero, product-list, footer.
  • Sections can include multiple blocks and usually expose settings you can edit in the theme editor.

• Blocks

  • Small, repeatable components that live inside sections.
  • Use blocks for repeatable content items like slides in a slider, cards in a features grid, or list items inside a component.
  • Blocks are the building bricks you add/drag inside a section instance.

• Snippets

  • Tiny pieces of markup or helper UI used across multiple sections/templates (buttons, icons, price tags).
  • Snippets are not directly configurable in the editor; they are included where needed.

Rule of thumb:
Use sections for page composition, blocks for repeated items within a section, and snippets for tiny reusable markup.

layout/ folder — what it contains & how it works

• The layout/ folder contains the global skeleton of your site.
• Typical files:
  • theme.liquid (main skeleton — loads header, footer and page content)
  • bare.liquid (minimal wrapper for special pages or popups)
• Layout files typically:
  • Include global meta tags and assets.
  • Render the header and footer snippets/sections.
  • Provide a {{ content }} or equivalent placeholder where templates/ content is injected.

Why layout matters: If a layout file is missing or misconfigured, even correct templates will render incorrectly — header or footer may be missing, assets may not load, or the page structure may break.

templates/ folder & route syncing

• Each route is mapped to a template file inside templates/.
  • Example: route /services → templates/services.liquid (and/or templates/services.json)
• Template types:
  • .liquid — contains the HTML + Liquid tags to render dynamic content.
  • .json — describes which sections (and section order) appear on that page (visual page-builder friendly).
• Sync flow:
  1. When a route is created, the system looks for a matching template in templates/.
  2. If a matching .liquid/.json template exists, it is used to render the route.
  3. If not found, the system falls back to the default template (e.g., templates/index.liquid).
  4. Routes can be manually linked to a specific template in route settings (if supported).

Tip: Keep template filenames simple and matching route slugs for predictable syncing.

How module data appears in templates

• Modules (Blog, Products, Services, etc.) supply the data the template renders.
• Example usage inside a template:
  • {{ service.title }}
  • {{ product.price }}
• The system injects the correct module object into the template based on the route and module linkage. No backend code is required from the user — templates use simple placeholders to display module data.

JSON templates & page building (how sections + blocks are composed)

• A .json template defines which sections are present and their order on a page (visual editor friendly).
• Each section can have a list of blocks configured in that template instance.
• Example (conceptual) JSON structure:

{
"sections": {
	"main_section": {
		"type": "slide-show",
		"blocks": {
			"slide_0": {
				"type": "image",
				"settings": {
					"alignment": "center",
					"heading": "Welcome Banner",
				}
			},
			"slide_1": {
				"type": "image",
				"settings": {
					"button_text": "Learn More",
					"button_link": "/pages/about",
					"image_url": "path/to/image2.jpg"
				}
			}
		},
		"block_order": [
			"slide_0",
			"slide_1"
		],
		"settings": {
			"container": "fullwidth",
			"arrow_active": true
		}
	}
},
"order": [
	"main_section"
]
}