> ## Documentation Index > Fetch the complete documentation index at: https://docs.launchmystore.io/llms.txt > Use this file to discover all available pages before exploring further. # Layouts > How layout files wrap rendered pages in an HTML shell # Layouts A **layout** is the outermost HTML wrapper for a rendered page — the ``, ``, ``, and `` tags, plus any global navigation, scripts, and styles that appear on every page. Every theme ships at least one layout file (`layout/theme.aqua`), and that file is used for every page render unless the page explicitly chooses otherwise. *** ## The default layout `layout/theme.aqua` is the canonical entry point for every rendered page. It receives two special variables from the renderer: | Variable | Holds | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | `{{ content_for_header }}` | Platform-injected `` content: analytics scripts, meta tags, OG tags, `` preloads, customizer-mode scripts. | | `{{ content_for_layout }}` | The rendered page body — the result of running the resolved template through Liquid. | A minimal but complete layout: ```aqua theme={null} {%- if settings.favicon != blank -%} {%- endif -%} {{ page_title }} {% if page_description %} {% endif %} {{ content_for_header }}

{% sections 'header-group' %}

``` ### Requirements A layout file **must**: 1. Be a complete HTML document — open with `` and emit ``, ``, and ``. 2. Include `{{ content_for_header }}` somewhere inside ``. Without it, analytics scripts, the theme-editor bridge, view-transition markers, and OG tags will not be injected. 3. Include `{{ content_for_layout }}` somewhere inside ``. Without it, the rendered template body is dropped silently and the page looks empty. A layout **should**: * Reference theme settings via `{{ settings.* }}` for global CSS variables, fonts, and feature flags. * Render `{% sections 'header-group' %}` and `{% sections 'footer-group' %}` if the theme uses section groups for navigation (most modern themes do). * Set `lang="{{ request.locale.iso_code }}"` on `` so screen readers pick the right voice. A layout **must not**: * Use `{% section '' %}` or `{{ content_for_layout }}` more than once per render. Only the first occurrence is populated; later references return empty. * Include a `{% schema %}` block. Schemas live on sections and blocks, not layouts. *** ## What `content_for_header` injects The platform reserves `content_for_header` for HTML that must be present in `` for the storefront to work correctly. At minimum, it includes: * Analytics and tracking scripts that the merchant has enabled (GA4, GTM, Meta Pixel, TikTok Pixel, Pinterest, Snapchat, plus any installed app scripts). * The theme editor's communication bridge (only when `request.design_mode` is true). * View-transition markers, preconnect hints, and resource preloads computed from the current page's data. * Open Graph and Twitter Card metadata for the current page. You don't need to handle any of this manually — just emit `{{ content_for_header }}` and the renderer fills it in. If you also need to inject your own `` content per page, do that **through the section schema** (the editor exposes a "Theme settings → Advanced → Custom code" pattern in many themes) rather than hardcoding into the layout. That way merchants can edit without touching template files. *** ## Multiple layouts A theme can ship more than one layout. Each is a separate file under `layout/`: ``` layout/ ├── theme.aqua ← default, used for every page unless overridden ├── password.aqua ← used when the store is in "coming soon" mode └── minimal.aqua ← used by templates that opt in ``` ### Selecting an alternate layout from a JSON template A JSON template can name a layout file: ```json theme={null} // templates/page.legal.json { "layout": "minimal", "sections": { "main": { "type": "page", "settings": { "show_meta": false } } }, "order": ["main"] } ``` The renderer reads `"layout": "minimal"`, then loads `layout/minimal.aqua`. The page body is rendered into `{{ content_for_layout }}` of that file instead of the default. If the file doesn't exist, the renderer falls back to `layout/theme.aqua` with a warning in the logs. ### Selecting an alternate layout from a Liquid template A `.aqua` / `.liquid` template can declare its layout with the `{% layout %}` tag at the top of the file: ```aqua theme={null} {# templates/gift_card.aqua #} {% layout 'gift_card' %}

``` This is exactly equivalent to the JSON `"layout": "gift_card"` form. Both resolve to `layout/gift_card.aqua`. ### The `password.aqua` layout Stores in "coming soon" mode return `templates/password.json`. By convention this template sets `"layout": "password"`, which renders into `layout/password.aqua` — a stripped-down shell with just the password form and no global navigation. ```json theme={null} // templates/password.json { "layout": "password", "sections": { "main": { "type": "password-form" } }, "order": ["main"] } ``` ```aqua theme={null} {# layout/password.aqua — example minimum #} {{ shop.name }} — Opening soon {{ content_for_header }} {{ content_for_layout }} ``` *** ## Bypassing the layout For AJAX section reloads, embedded widgets, and email rendering, you often want the rendered body **without** any HTML wrapper. There are two ways to do this. ### `{% layout none %}` in a Liquid template In a `.aqua` / `.liquid` template, declare: ```aqua theme={null} {% layout none %}

``` The renderer treats the file body as the entire response — no ``, no ``, no header / footer groups. The single `

` is returned as-is. ### `"layout": false` in a JSON template A JSON template can opt out of the layout the same way: ```json theme={null} { "layout": false, "sections": { "card": { "type": "product-card-fragment" } }, "order": ["card"] } ``` The renderer runs the sections in `order`, concatenates their HTML, and returns it directly. ### URL-level bypass Section AJAX fetches use a different mechanism — `?section_id=` is intercepted by middleware and routed to `/api/themes/render-section`, which renders one section without ever loading a layout. You typically don't write `?section_id=` URLs yourself; the theme's JavaScript builds them (cart drawer updates, infinite scroll, predictive search, etc.). `{% layout none %}` and `"layout": false` skip `{{ content_for_header }}` entirely. If you're rendering an embeddable widget that still needs analytics, choose a minimal layout file rather than `none`. *** ## Layout selection precedence When the renderer chooses which layout to use, it consults these sources in order: 1. **`{% layout '' %}` or `{% layout none %}`** inside a Liquid template. Wins over everything else. 2. **`"layout": ""` or `"layout": false`** in a JSON template. 3. **`?layout=` query parameter** on the request URL. Reserved for internal tooling (customizer preview, render-section endpoints) and not generally used by storefront URLs. 4. **`layout/theme.aqua`** — the default. The resolved name is suffixed with `.aqua` (or `.liquid` if `.aqua` is absent) and looked up under `layout/`. *** ## The `request` and `template` globals Layouts have access to the full global object catalogue. Two are particularly useful in a layout: * `request` — the current request. Most useful fields: * `request.design_mode` — `true` when rendering inside the theme editor's preview iframe. Use this to load the editor bridge or extra debug helpers. * `request.locale.iso_code` — the active locale's two-letter code (e.g. `"en"`, `"fr"`). Set this on ``. * `request.path` — the request path. * `template` — the active template name (`"product"`, `"collection.featured"`, etc.). Useful for body classes: ```aqua theme={null} ``` `settings` (theme settings from `config/settings_data.json`) is also available globally — most layouts emit them as CSS custom properties: ```aqua theme={null} ``` *** ## A note on `checkout.liquid` LaunchMyStore's checkout is **not** rendered through Liquid. It's a native surface built into the platform, with extensibility provided through checkout extensions and post-purchase extensions rather than a Liquid template. If your theme ships a `layout/checkout.liquid` file (checkout layouts in some Liquid platforms), it is ignored. Checkout customization happens through: * **Checkout extensions** — UI extensions injected at named extension points. * **Post-purchase extensions** — pages shown after order placement. * **Branding** — colors, fonts, and logo are read from the merchant's brand settings, not from `checkout.liquid`. See the [Extensions documentation](/extensions/checkout-extensions) for the supported customization model. *** ## Worked example: a full `theme.aqua` ```aqua theme={null} {%- if settings.favicon != blank -%} {%- endif -%} {%- render 'meta-tags' -%} {%- render 'stylesheets' -%} {%- render 'fonts' -%} {%- render 'theme-styles-variables' -%} {%- render 'color-schemes' -%} {% if request.design_mode %} {%- render 'theme-editor' -%} {% endif %} {{ content_for_header }} {% render 'skip-to-content-link', href: '#MainContent', text: 'accessibility.skip_to_text' %}

{% sections 'header-group' %}

``` Every piece of this is editable by the theme author. The two `{{ content_for_* }}` calls are the contract — everything else is yours. *** ## Next steps Where layout files live among the rest of the theme. What `content_for_layout` actually receives. Translating storefront copy across locales. `request`, `template`, `settings`, and other globals.

{{ gift_card.id }}

{{ product.title }}