Compiler workspace
HTML to Shopify Liquid
Paste a single HTML module — hero, FAQ, banner, or grid — and generate a section.liquid file with Liquid variables, {% schema %} JSON, presets, and scoped CSS. Review output here, then test in your staging theme before publishing.
Flat mode for fixed layouts. Block mode for repeatable rows. Validation checks catch common issues — human review is still required for production storefronts.
How to use this workspace
Convert static HTML into merchant-editable Shopify sections
This workspace turns a single HTML module into a production-oriented section.liquid file — Liquid variables, {% schema %} JSON, scoped CSS, and optional blocks. Paste design markup, choose Flat or Block mode, generate output, and review before adding files to your theme.
Generated code follows Online Store 2.0 conventions, but you should always test exports in a staging theme. Validation checks catch common schema and Liquid issues — they do not replace human review for accessibility, performance, and brand fit.
Workflow
Practical conversion workflow
- 01
Paste HTML
Drop a single section's markup — hero, FAQ, banner, or card grid. One module per conversion works best.
- 02
Select Flat or Block
Flat for fixed layouts with indexed settings. Block for repeatables merchants add, remove, or reorder.
- 03
Generate & preview
Run conversion, inspect Liquid output, schema JSON, and scoped CSS in the workspace preview.
- 04
Copy or download
Export section.liquid and add it to your theme's sections/ folder.
- 05
Test in Shopify
Add the section via JSON template or theme editor, fill settings, and QA on mobile before publishing.
Expected input and output
Expected input
- A single section's HTML — not an entire multi-page site
- Semantic markup: headings, paragraphs, images, links, lists
- Figma Dev Mode, Tailwind, or plain HTML exports
- Repeatable rows with identical structure for Block mode
- Class names you can map to scoped CSS (utilities are normalized)
Expected output
- A section.liquid file with Liquid variables for editable content
- Valid {% schema %} JSON with typed settings and presets
- Scoped CSS using section.id — no global style pollution
- Optional {% for block in section.blocks %} loops in Block mode
- Output ready for review — not guaranteed production-perfect without tuning
Before you convert
Common mistakes before conversion
Pasting an entire page
The workspace targets one section module. Split landing pages into hero, features, FAQ, and grid chunks before converting.
Leaving hardcoded CDN image URLs
Replace asset URLs with placeholder images or note which nodes should become image_picker settings after export.
Mixing unrelated components
A hero plus footer plus product grid in one paste confuses block detection. Convert each pattern separately.
Relying on inline JavaScript
Script tags are stripped for theme safety. Plan CSS-only interactions or theme-native patterns before conversion.
Skipping semantic structure
Div soup without headings or repeatable row patterns makes setting detection less accurate. Use clear HTML hierarchy.
After you export
Tips after conversion
Rename setting IDs for merchants
Generated IDs are stable but technical. Relabel schema labels so store owners understand headline vs subhead vs CTA.
Match parent theme tokens
Swap hardcoded font sizes and colors for CSS variables your theme already defines.
Add max_blocks where needed
Cap repeatable blocks on sliders and logo strips so merchants cannot break layout with unlimited rows.
Test empty image states
Open the theme editor with blank image_picker values — guard image_url filters so empty picks do not break markup.
Run theme check before merge
Use Shopify CLI theme check or manual review for Liquid syntax, schema validity, and accessibility on your target theme.
Production safety
Why review generated Liquid before production?
The converter accelerates structure — schema, blocks, and scoped CSS — but your parent theme, merchant content, and storefront context are unique. A staging review prevents surprises on launch day.
Theme editor behavior
Confirm settings appear with readable labels, presets register in Add section, and merchants can edit without breaking layout.
Responsive breakpoints
Design HTML often targets desktop width. Test mobile and tablet in Shopify preview — adjust scoped CSS where grids collapse.
Accessibility
Verify heading order, alt text on images, focus states on interactive elements, and color contrast against your live theme.
Performance
Avoid oversized images, unnecessary DOM depth, and unguarded Liquid loops. Profile on collection and product templates if relevant.
Troubleshooting
Common issues and fixes
Section does not appear in Add section
Check that {% schema %} JSON is valid — no trailing commas. Confirm a preset exists and the section file is in sections/ with the correct filename.
Preview looks unstyled or broken
Preview approximates layout; your parent theme's CSS variables and fonts are not loaded. Test in a staging theme for accurate visuals.
Block mode detected too few or too many rows
Ensure repeatable HTML rows share identical structure. Convert complex grids as separate passes or switch to Flat mode for fixed layouts.
Images show blank on the storefront
Add image_picker fallbacks and guard image_url filters when settings are empty. Merchants may save before uploading media.
Validation warnings after export
Review each warning in context — some are suggestions, others flag schema or Liquid issues. Fix before publishing to production.
FAQ
Converter workspace — frequently asked questions
Practical answers about input, export modes, preview limits, and Shopify deployment. For broader topics, see the HTML to Liquid converter guide.
What HTML works best in the converter workspace?
Paste one section module at a time — a hero, FAQ accordion, banner, or product grid. Semantic HTML with clear headings, images, links, and identical repeatable rows converts most reliably.
What file do I get after conversion?
A section.liquid file containing Liquid markup, optional scoped CSS, and a {% schema %} block. Copy it into your theme's sections/ folder and reference it from a JSON template.
When should I choose Flat mode vs Block mode?
Use Flat for single-instance heroes and fixed layouts where settings map to indexed fields. Use Block when merchants need to add, remove, or reorder rows like FAQ items or slides.
Can I paste HTML that includes JavaScript?
Inline scripts are removed for theme safety. Plan CSS-only interactions, details/summary patterns, or theme-native slider utilities instead of embedded JS.
Why does workspace preview differ from my live Shopify theme?
Preview validates structure without your parent theme's fonts, CSS variables, or global styles. Always test exported sections in a staging theme for accurate results.
Do I need Shopify CLI to use exported sections?
No for basic use — you can upload via the theme editor code view or admin. CLI is recommended for teams using Git, theme check, and staged deployments.
What should I verify after every export?
Schema validity, preset registration, empty image states, mobile layout, link targets, and accessibility. Generated output accelerates structure — human review is still required.
Can a store owner use the converter without developer experience?
Store owners can paste HTML and explore output, but deploying sections to a live theme requires theme access and Shopify best practices. We recommend a developer review before publishing.