Theme editor workflow

Documentation scope: Guild 0.1.x pre-release builds. The exact public release version will be confirmed in the changelog before Theme Store publication.

Use this guide when you are not sure where a change belongs in the Shopify theme editor. The safest setup order is: Shopify Admin content first, then global theme settings, then templates, then sections, then blocks, and only then apps or custom code.

Understand the editing layers

Guild is the theme. Home is the Shopify industry category targeted by the first public demo and listing direction; it is not the theme name or a preset name. Theme presets, templates, sections, and blocks are separate editing concepts inside the shared Guild feature library.

Layer	What it controls	Practical rule
Guild theme	The shared storefront feature set and theme code.	Do not treat the theme as a blank page builder. Start from the supplied templates and presets.
Industry category	Theme Store classification and merchant-fit direction, such as Home. This is commercial/demo context, not an editor layer.	Do not use an industry category as if it were the theme or preset name.
Theme preset	A starting configuration within Guild. It can change starter styling and defaults without creating a separate feature library.	Use it as a starting point, then replace sample content with real store content.
Template	The section composition for a page type or assigned resource.	Choose the correct product, collection, page, article, cart, or search template before editing individual sections.
Section preset	A ready-made section structure, such as Store highlights, Testimonials, or Gallery.	Add the preset that is closest to the intended job instead of rebuilding it from structural blocks.
Section	A major page area, such as Hero slideshow, Featured collection, or FAQ accordion.	Configure the section-level layout before editing its blocks.
Block	Content or a focused control inside a section.	Edit the block that owns the visible content. Use Row, Column, and Box only for deliberate advanced compositions.
Theme settings	Store-wide visual and utility defaults.	Set these before styling every section independently.

A merchant should normally move from real Shopify data to global settings, then to a template, a section preset, and its content blocks. Structural blocks and custom code are optional tools, not the default setup path.

Start with the source of the content

Before changing layout settings, check where the content should live.

What you want to change	Start here	Why
Product title, price, variants, images, description, vendor, SKU, inventory, collections, tags, metafields	Shopify Admin product data	Theme settings cannot fix missing or incorrect product data.
Collection title, description, image, products, sort/filter data	Shopify Admin collection data and Shopify Search & Discovery	The theme can display collection data, but Shopify controls the source data and filter configuration.
Header and footer menu links	Shopify Admin navigation	The theme editor selects menus and layouts; Shopify Admin stores the menu items.
Store policies, legal pages, shipping/returns pages	Shopify Admin pages and policies	Publish real policy content before linking to it from the footer.
Overall colors, typography, spacing, buttons, inputs, logo, social links	Theme settings	These settings create the global baseline for new sections.
A page layout or product/collection/cart/search structure	Template editor	Templates control which sections appear on a page type.
A content area inside a template	Section settings and section blocks	Sections control layout areas and blocks control the content inside them.
A one-off embed or snippet from another provider	Custom HTML, Custom Liquid, or app embed	Use carefully, and test privacy, performance, layout, forms, data handling, and update impact. The code author or provider owns custom form submission and validation behavior.

Use this decision order

1. Fix Shopify Admin content first. Product, collection, navigation, policy, and store data should be correct before the theme tries to present it.
2. Set Theme settings before section-level styling. Colors, typography, font sizes, spacing, buttons, inputs, radius, shadows, and brand assets should be reviewed early.
3. Choose the right template. Product, collection, page, blog, article, cart, search, password, 404, and list collections templates have different jobs.
4. Add or edit sections. Use sections for major page areas such as hero, catalog route, product merchandising, contact form, FAQ, newsletter, map, or rich content.
5. Edit blocks inside the section. Use blocks for text, media, buttons, cards, product lists, form fields, utilities, and nested content.
6. Use apps and custom code last. Apps, Custom HTML, Custom Liquid, and code edits can affect updates, privacy, support scope, accessibility, performance, and form/data behavior.

Understand global settings vs section settings

Use Theme settings when a choice should apply broadly across the store.

Good examples:

• main color schemes;
• heading and body typography;
• desktop and mobile text sizes;
• section spacing baseline;
• button and input shape;
• media radius;
• logo, favicon, and social media preview image.

Positive Custom margin, Custom mobile margin, and boxed Custom bottom spacing controls use the shared spacing scale as a percentage: 100% equals the normal 1x spacing amount, and the editor adjusts it in 25% (0.25x) steps.

Use section settings when a choice belongs to one page area.

Good examples:

• section width;
• background width;
• color scheme for one banner;
• image ratio for one card grid;
• content position for one hero;
• padding for one section;
• number of products or collections shown in one section.

Avoid styling every section separately before the global baseline is set. That makes the store harder to maintain and usually increases support friction.

Work from template to section to block

When editing a page, use this path:

1. Open the correct page or template in the theme editor preview.
2. Select the section in the left sidebar.
3. Review section-level layout settings first.
4. Expand the blocks inside that section.
5. Edit the specific block that owns the content.
6. Preview desktop and mobile before duplicating the pattern elsewhere.

If a setting appears to do nothing, check whether the selected block has its own setting overriding the section, whether the content is coming from Shopify Admin data, or whether the selected preview page does not contain the state you are editing.

For supported Row, Column, Box, Media, Divider, Icon, Quote, Star rating, and Breadcrumbs blocks, open Advanced > Show advanced options > Display mode when one block should be visible only on mobile or desktop, or hidden on one of those ranges. The Mobile only and Desktop only choices both exclude the 761px-1000px tablet range; Hide on mobile and Hide on desktop keep that tablet range visible. Prefer this block setting over duplicating an otherwise identical section just to change one block's visibility.

Edit a generic Card

Generic Cards keep the editor hierarchy shallow so the content order is easier to understand.

1. Select Card and configure its layout, boxed mode, spacing, and link behavior.
2. Add Card media only when the card needs an image, video, map, model, or other media. Blocks nested inside Card media appear over the media as overlay content.
3. Add the main Heading, Text, Buttons, Icon, Quote, Tags, or other supported content blocks directly under Card. There is no separate Card content wrapper.
4. Use Card footer when content should remain after the main card content. It accepts the same content block choices as Card and Custom card; the default action is nested as Buttons > Button. The Footer stays at the end of the card and does not appear on the storefront when it has no usable content.
5. Reorder the direct content blocks to change their reading order, then check the card on desktop and mobile.

Use only the areas the card needs. A card can contain media only, direct content only, a Footer only, or a combination of all three. Keep important explanatory copy in the main content area rather than placing all text over an image.

Use the right preview state

Some settings only make sense when the preview has matching data.

Area	Preview with
Product page	A real product with images, variants, price, description, and any metafields or selling plans the store uses.
Collection page	A real collection with enough products to test grids, pagination, sorting, and filters.
Search page	One query with results and one query with no results.
Cart page	At least one cart item, then an empty cart state if the store uses custom empty-cart content.
Contact page	A live Shopify preview URL when checking form submission, success, error, and hCaptcha behavior.
Popup sections	The popup group and the trigger or automatic display settings that open the popup.
Header mega menu	A menu with nested items and the relevant mega menu block selected in the sidebar.

Do not judge a setting as broken from an unrelated preview state. For example, collection filters need Shopify Search & Discovery data and products that match the configured filters.

Choose sections by job, not by visual similarity

Use these starting points:

Goal	Usually start with
Flexible editorial layout, cards, logos, trust bars, custom compositions	Rich content
Opening visual or campaign hero	Hero slideshow or Media with content
Image plus short story or call to action	Media with content
Product merchandising	Featured collection, Related products, Complementary products, Recently viewed, Shop the look
Collection/category route	Featured catalog
Store contact page	Contact form plus optional Google map, FAQ, and supporting content
Collapsible support content	FAQ accordion
Tabbed product or support information	Tabbed content
Newsletter capture	Newsletter form or Newsletter popup
One-off trusted embed	Custom HTML or Custom Liquid

Do not use Custom HTML or Custom Liquid only to recreate a layout that an existing section can already build.

Be careful with advanced blocks

Some block families are powerful because they can create nested content structures. That flexibility is useful, but it also means a merchant can overbuild a page quickly.

Use a simpler section or preset when the goal is simple. Start with the closest ready-made preset, replace its content, and adjust its layout. Use nested structural blocks only when the section needs a deliberate custom structure such as cards, columns, rows, forms, product details, or content groups.

Before publishing a heavily nested layout, check:

• mobile stacking;
• text length;
• image crop;
• button order;
• keyboard navigation;
• app embeds;
• Custom HTML or Custom Liquid;
• desktop and mobile spacing.

Do not edit helper or system areas unless the docs mention them

Some theme areas support storefront behavior rather than merchant content. Examples include quick view, pickup availability, and helper popup flows. If an area has no useful merchant-facing settings, avoid trying to use it as a normal content section.

Predictive search is configured through Header > Main search, not by editing the Predictive search helper section directly. Main search controls whether predictive results are enabled. Optional simple result groups are composed with Search suggestions child blocks: each block selects Suggestions, Collections, Brands, or Content and owns its own heading, Content-list-style layout, spacing, typography, and responsive display settings. Use Row - search and Column - search to arrange those blocks, and Search visibility group with Context: Predictive search when nested content should depend on available Products or Search suggestions. Normal Heading/Buttons blocks provide supporting content; a Button can use Action behavior: Search results to target the current predictive-search query. Product-result presentation is configured through the movable/removable Search results list child; when present, it reuses the same Product-card controls as the Search page without creating a second Product renderer. While Main search or one of its child blocks is selected in the Theme Editor, Guild keeps the predictive panel open and renders editor-only Product and Search-suggestion preview content so result presentation can be styled without repeatedly opening search; this does not change normal storefront opening behavior.

For Header mega menus, use Mega menu panel or Custom mega menu to control the menu surface. Both support surface color scheme and shadow controls; Mega menu panel also exposes its own padding control, while Custom mega menu keeps its existing padding options. Generated Mega menu headings can use Heading or Body typography, Body-only Text style, Font weight, Font size, Uppercase, alignment, and margin. Custom mega menu tabs can contain normal Product lists with their own Product item composition. Keep deeply nested custom compositions restrained because Shopify enforces a maximum block nesting depth.

Use the documented page templates, sections, and blocks instead. If a helper behavior looks wrong in an unmodified copy of the theme, use Troubleshooting or Contact support.

Use dynamic sources deliberately

Dynamic sources are useful when one template should show different content per product, collection, page, or metafield. Shopify manages metafield definitions and values; Guild exposes compatible settings that can connect to those sources. For platform setup, see Shopify's sections and blocks and metafields documentation.

Use dynamic sources for content that belongs to the Shopify object, such as care information, dimensions, material, product badges, collection descriptions, or page-specific content.

For collapsible product information, enable Show advanced options in an Accordion item and connect its Dynamic content rich-text setting to a compatible product metafield, such as a rich-text shipping-information field. Shopify needs a compatible setting type to offer the dynamic-source connection, so the control remains rich text rather than a special metafield-only field. The checkbox only reveals the advanced control in the editor; collapsing it does not disconnect the saved source. On the storefront, the entire Accordion item is omitted when Dynamic content and all nested blocks are empty, so an empty metafield cannot leave a heading-only accordion.

Do not use dynamic sources as a workaround for missing product data. If every product needs the same correction, fix the product data or the shared template structure instead.

Configure localization in Shopify before adding selectors

Country and language selectors expose Shopify localization options; they do not create them.

• Add Country selector only after Shopify Markets provides more than one country or region to the Online Store.
• Add Language selector only after more than one storefront language is published.
• If a selector has only one valid choice, it may correctly remain hidden.
• After changing Markets or published languages, save and refresh the theme editor and preview the intended storefront context.

Apps and custom code should come after the theme setup

Before adding an app, Custom HTML, Custom Liquid, or code edit:

1. Duplicate the theme.
2. Check whether the built-in theme settings can solve the task.
3. Add the app or custom code only to the duplicate first.
4. Test desktop, mobile, product, collection, cart, forms, and page speed impact. For a custom or app-provided form, test its endpoint, validation, success/error output, accessibility, consent, spam protection, and data handling separately.
5. Record what was changed so it can be reviewed during future updates.

Standard Guild support can ask you to reproduce an issue in an unmodified copy of the theme.

Quick workflow for a confusing editor task

1. Write down the exact page and goal.
2. Confirm the Shopify Admin data exists.
3. Open the matching template in the theme editor.
4. Select the section in the sidebar.
5. Check section settings first.
6. Expand blocks and edit the block that owns the visible content.
7. Preview mobile.
8. Test the relevant storefront state.
9. Use Troubleshooting if the result still does not match the setting.
10. Contact support when the documentation does not resolve the issue. Include the affected URL, Guild version, steps to reproduce, expected result, actual result, and redacted screenshots or a short recording; test an unmodified duplicate first when practical for suspected bugs.

Related guides

• Section guides
• Theme settings
• Templates
• Troubleshooting