LiquidDoc and Theme Check: keeping snippets maintainable

Every theme eventually has the snippet nobody dares touch. It takes a few variables, nobody remembers which are required, and a change in one place breaks three others.

Shopify has two tools that make this much better: LiquidDoc to describe what a snippet expects, and Theme Check to catch mistakes.

LiquidDoc: a documented interface

LiquidDoc lets you declare a snippet's (or block's) inputs at the top of the file, inside a doc tag. The annotations are:

• @description says what it's for.
• @param documents each input, with a type and a description.
• @example shows how to call it.

Supported parameter types include string, number, boolean and object. A parameter in square brackets is optional.

{% doc %}
  Price display snippet

  @param {number} price - Price value
  @param {boolean} [show_compare_at] - Whether to show compare-at price

  @example
  {% render 'price', price: product.price, show_compare_at: true %}
{% enddoc %}

That header is both documentation and a contract.

What you get from it

With editor support, you get:

• Hover documentation over a render call, so you see what a snippet expects without opening the file.
• Autocomplete for parameter names.
• Validation warnings when a required parameter is missing.
• Type checking, with suggestions for fallback values.

And Theme Check can validate calls against the documentation, so a mismatch is flagged while you write, not after it breaks on a product page.

Why this matters for teams

On a team, or with a store that has several developers over several years, the expensive problems are communication problems. Who knows that card.liquid needs a product object and silently renders nothing without it?

A documented interface helps with:

• Onboarding. New developers read the contract instead of reverse-engineering.
• Refactoring. You can change a snippet knowing what its callers are supposed to pass.
• Review. Reviewers can check calls against the declared inputs.
• Fewer silent failures. A missing parameter becomes a visible warning.

A practical approach

1. Start with the most reused snippets. Cards, price displays, icons and buttons.
2. Document what exists first. Read how the snippet is actually called, then write the interface to match. Don't invent requirements.
3. Mark optional parameters honestly. Over-requiring causes noisy warnings.
4. Add an example. The example is what people copy.
5. Run Theme Check in your normal workflow, and in CI where you can, so new code is held to the same standard.

What it doesn't do

LiquidDoc documents inputs; it doesn't make bad snippets good. A 300-line snippet with fifteen parameters needs splitting, not documenting. Use the exercise of writing the interface as a prompt: if the contract is hard to describe, the design probably needs work.

Pair it with the other hygiene

LiquidDoc and Theme Check work well alongside fixing strict-parser violations and the section and block patterns in Online Store 2.0. Together they turn a theme from something you're afraid of into something you can maintain.

Check Shopify's current LiquidDoc documentation for the full list of supported tags and types.