HTMLtoLiquidConverter.com was not a startup pitch — it was a rescue habit that got productized. A wholesale apparel rebuild with twenty-three homepage modules due before Black Friday was the deadline that turned Dhruv's schema inference prototype into the public converter workspace agencies use today.

HTMLtoLiquidConverter.com was not a startup idea we pitched at a whiteboard. It was a rescue habit that got productized. For nine combined years building Shopify stores — supplements, furniture, B2B wholesale, luxury apparel — we pasted Figma exports into section files the same way every agency does: duplicate a reference section, strip the markup, rewrite settings by hand, pray the {% schema %} block validates, discover at QA that the FAQ module has twelve hardcoded details elements because someone was rushing. The tool exists because that loop failed clients one too many times. Below: the pain points, the workflow slot it fills, what shipped first, what broke, and what we would tell another agency lead considering the same path. Follow section workflow for the delivery pipeline it plugs into.

The client pain point that would not go away

Every OS 2.0 rebuild starts with the same promise to the merchant: you will edit this homepage yourself after launch. Every rebuild ends with developers translating static HTML into section.settings, block loops, image_url filters, and presets — work that is tedious, error-prone, and invisible to the client until something breaks in the theme editor. We tracked our own time on a six-module homepage last year: intake and naming, four hours; conversion and schema, eleven hours; JSON template wiring, two hours; theme editor QA, three hours. More than half the build sat in conversion. Not design. Not Liquid logic for cart drawers or metafields. Copy-paste scaffolding. When half a project is scaffolding, you either systematize it or you burn margin on every flat-fee quote.

What merchants actually experience when conversion is rushed

Merchants do not file tickets that say "your schema ids are inconsistent." They say the FAQ section will not let them add a thirteenth question, or the hero looks empty, or they changed the button text and the link stopped working because someone used a text setting for a URL. We fixed a Prestige fork last winter where a previous agency hardcoded announcement bar copy in Liquid — the client was editing theme settings that did nothing. The storefront looked fine. Trust was not. Our conversion standard is: every visible string in the approved Figma frame maps to a setting or block field before merge. That standard is tedious to maintain by hand across twenty modules. It is almost mechanical for a tool that reads the HTML structure.

On wholesale rebuilds we maintain a module inventory spreadsheet before conversion: Figma frame name, planned section filename, Flat versus Block decision, and target JSON template key. A typical twenty-module homepage maps to sections/hero-split.liquid through sections/logo-marquee.liquid — filename becomes the section type permanently. That inventory prevented duplicate heroes on a 2024 apparel client where design had renamed modules mid-sprint without telling development.

Manual conversion problems we hit on every agency project

Manual HTML-to-Liquid conversion fails in predictable ways. Developers hardcode eyebrow text that marketing changes weekly. Image tags stay as static src attributes instead of image_picker settings with image_url and width parameters. Repeating rows — testimonials, logos, FAQ items — get copied as twelve sibling divs instead of block loops with block.shopify_attributes. CSS targets bare h2 and img selectors, then a collection page inherits the hero's font-size. Presets arrays stay empty, so the section never appears in Add section on JSON templates. None of these are mysterious bugs. They are Friday-at-5pm omissions when the sprint board says deploy Monday.

• Missing presets — section invisible in theme editor Add section panel.
• Hardcoded repeatables — merchant cannot add FAQ row thirteen on launch day.
• Text settings for URLs — breaks when clients paste full paths with UTM parameters.
• Unscoped CSS — Dawn product thumbnails inherit border-radius from a testimonial section.
• Placeholder attributes mistaken for real settings — spurious color pickers from data-theme attributes.
• Schema ids renamed after merchant content exists — wipes theme JSON on deploy.

Why we did not just buy another tool

We tried the obvious options first. Generic HTML-to-template converters do not understand Shopify section schema types, {% stylesheet %} scoping, or the difference between a flat hero and a block-based FAQ. AI chat tools hallucinate filter names, invent nonexistent Liquid tags, and output schema that looks valid until Theme Check explodes. Internal agency snippets helped for heroes but not for the long tail of client-specific modules — comparison tables, ingredient grids, wholesale price bands. We needed something that lived in our stack: paste HTML, get scoped Liquid plus first-pass {% schema %}, edit labels for merchant language, run Theme Check, merge. When nothing fit that slot without adding review work, we built the slot.

The agency workflow slot the tool was designed for

Our workflow already had phases — intake, conversion, schema audit, JSON templates, QA, handoff. Documented in Shopify Section Workflow We Use on Every Client Project. Conversion was the bottleneck. The tool does not replace schema review; it front-loads structure so review is fifteen minutes instead of three hours. Dhruv runs intake and naming; Nishad runs conversion output through schema audit and CSS scoping checks. Merchants still get section tutorial handoffs and Loom walkthroughs. The converter is developer infrastructure — like Theme Check, not like the theme editor. If you read our story, you know we optimize for repeat client work, not one-off hacks. The tool is the same philosophy: boring reliability beats heroic midnight fixes.

The first prototype — built on a deadline, not a pitch deck

The first version was ugly and local-only. A wholesale client needed twenty-three homepage sections before Black Friday — inventory spreadsheets, Dawn fork, duplicate theme, the usual. Module seven was another split hero with eyebrow, heading, dual CTAs, and background media. Dhruv had rewritten that scaffolding four times in six weeks across different clients. On a layover he sketched a parser: detect text nodes in semantic headings, map buttons to url settings, wrap CSS under section.id, emit a blocks array when it sees repeated class patterns. Nishad spent the weekend on validation — reject output without presets, flag bare img tags without image_picker, warn when details elements look like FAQ candidates stuck in flat markup. We used it internally on modules seven through twenty-three. The client hit Black Friday on time. We kept the prototype.

{%- comment -%} First-pass hero output pattern we still ship today {%- endcomment -%}

  {% if section.settings.eyebrow != blank %}
    
{{ section.settings.eyebrow }}
  {% endif %}
  
{{ section.settings.heading }}
  {% if section.settings.button_label != blank %}
    
      {{ section.settings.button_label }}
    
  {% endif %}


{% schema %}
{
  "name": "Hero split",
  "tag": "section",
  "settings": [
    { "type": "text", "id": "eyebrow", "label": "Eyebrow text" },
    { "type": "text", "id": "heading", "label": "Main headline", "default": "Built for everyday athletes" },
    { "type": "text", "id": "button_label", "label": "Button label" },
    { "type": "url", "id": "button_link", "label": "Button link" },
    { "type": "image_picker", "id": "background", "label": "Background image" }
  ],
  "presets": [{ "name": "Hero split" }]
}
{% endschema %}

From internal script to HTMLtoLiquidConverter.com

Internal tools stay internal until you maintain the same script in three places and forget which repo has the fixed version. We productized when rescue projects started asking how we converted modules so fast — other agencies on shared Slack channels, freelancers we mentored, junior devs on client teams. The converter workspace is the public shape of that script: paste HTML, choose flat or block mode, tune schema inference, copy Liquid, run through your existing audit. We did not add features because they sounded impressive. We added features because a real client module broke without them — video poster attributes, richtext fields for long FAQ answers, range settings tied to CSS clamp values, header settings to group Advanced layout toggles merchants should not touch daily.

Schema inference lessons from 120+ section builds

Schema is where manual conversion dies. Shopify has typed settings — image_picker, richtext, url, color_scheme — and merchants feel the difference immediately in the theme editor UI. Our inference rules came from audits, not documentation alone. If markup contains repeating siblings with the same class pattern, suggest blocks. If a tag is img with a placeholder src, suggest image_picker not text. If copy spans multiple paragraphs in a single container, suggest richtext. We cross-check edge cases against Shopify Schema Guide content we maintain for the team. Inference is wrong sometimes — that is expected. A wrong suggestion you delete in audit is cheaper than a missing setting you discover when the merchant uploads launch photography.

Client stories that shaped product decisions

A supplement brand needed an ingredient grid with six identical cards — image, title, short description, optional link. Manual conversion produced six setting groups named field_1 through field_18. Merchant-friendly labels took longer than the Liquid. The converter now names block settings from heading text in the HTML when it is sane, and falls back to generic labels we still fix in audit. A luxury apparel client needed FAQ accordions with richtext answers because compliance copy includes superscripts and linked citations. Flat text settings mangled the markup. We added richtext detection for answer containers. A B2B wholesale portal had price band tables that looked repeatable but were actually static — inference suggested blocks; we kept human override because wrong automation is worse than slow automation. Every feature flag in the product maps to a client module name in a private spreadsheet — redacted, but real.

Dawn themes, Figma handoffs, and the long tail of edge cases

Most clients sit on Dawn forks or themes that inherited Dawn's CSS variables. Conversion output must scope under section.id because Dawn's global typography is fragile. Figma exports love absolute positioning and desktop-first font sizes; our CSS pass adds clamp() suggestions where inference detects hero headings above 48px. Figma Dev Mode HTML is cleaner than copy-paste from random plugins — we still see exports with inline styles on every node and wrapper divs named Frame_427. The tool strips noise where safe; developers strip the rest. Black Friday and BFCM deadlines do not care about Figma plugin quality. The tool optimized for good-enough HTML from real exports, not laboratory markup.

FAQ sections — the module that sold us on block mode

FAQ modules appear on almost every homepage we ship. Merchants always add questions after legal reviews — shipping cutoff dates, allergen statements, return windows for holiday gifts. A flat FAQ with eight hardcoded details elements is a launch-week ticket factory. Block mode with presets seeding two faq_item rows is non-negotiable now. We wrote the block loop skeleton once in our section workflow article and the converter emits variants of it when it detects details/summary or accordion class patterns. Merchants see Add block. Developers see block.shopify_attributes on each row. Everyone sleeps before Cyber Monday.

Lessons learned building a developer tool as an agency development team

Building for yourself first kept the product honest. We did not add collaboration features before solo developers could paste, convert, and copy in under two minutes. We did not market to merchants. We dogfood on every client module before shipping inference changes — if Nishad's audit checklist grows, the release waits. Support requests from other agencies taught us more than feature brainstorms: preset naming, export formatting, validator messages that cite Shopify docs instead of saying invalid JSON. We also learned to document the why, not just the how. Why we built HTML to Liquid Converter and our developer profiles exist because developers trust tools built by people who still bill hours on theme work — not abstract SaaS brands.

• Dogfood every inference change on a paying client module before release.
• Never skip presets in generated schema — invisible sections erode trust fast.
• Validators should explain fixes in Shopify vocabulary, not parser jargon.
• Free core tooling is consistent with how we learned Shopify — open threads, shared snippets, rescue favors.
• The tool wins when it respects the audit phase, not when it claims to replace developers.

What we would build differently if we started today

We would ship block detection earlier — it was scarier to infer wrong block types than flat settings, but FAQ and logo marquee modules cost us more time pre-blocks. We would integrate Theme Check output in the UI sooner instead of copy-paste to CLI. We would document the fifteen-minute schema audit as a first-class checklist inside the converter workspace, not only in blog posts. We might add team workspaces earlier for agencies with three-plus implementers — shared snippet libraries, consistent naming exports. We would not change the core bet: first-pass structure, human audit, merchant-friendly labels, scoped CSS, presets always on.

How to use the tool on your next client module

Run the same phases we do. Complete intake and filename mapping before paste. Convert one module at a time — not the entire Figma page in one blob. Audit schema: labels, types, defaults, presets, block attributes. Scope and test CSS on collection and product templates, not only the homepage. Wire JSON templates only after QA on a duplicate theme. Hand off with section tutorial links and a short Loom. The converter removes the blank-file stare; it does not remove responsibility to the merchant. If you are evaluating whether the tool fits your agency, read why we built it, skim our story, then convert one real hero from your current client — not demo HTML from a landing page. You will know in twenty minutes if it earns a dock icon.

We did not build a converter because Shopify development is easy. We built it because the boring part should not steal the hours you need for cart logic, performance, and merchant trust.

Closing thought for agency developers

HTMLtoLiquidConverter.com is the product of client deadlines we almost missed, FAQ rows merchants added at midnight, and CSS that broke Dawn on a collection page nobody tested. It is not magic — it is structured first-pass output for people who still run schema audits and theme editor QA scripts. If that sounds like your week, the tool is for you. If you are learning sections for the first time, pair it with Shopify Schema Guide and our full section workflow. We are still building client stores. The converter ships when our own projects need it to. That is the only roadmap that ever made sense for us.