Skip to main content

LiquidDoc

LiquidDoc gives you a way to create a structured interface for Liquid snippets and blocks, allowing you to specify input parameters, add descriptions, and provide usage examples. These details are exposed through theme checks, code completions, and hover information, making development faster and more reliable.

Anchor to Why use LiquidDoc?Why use LiquidDoc?

It can be easy to make a small mistake when writing Liquid code:

  • Missing required parameters don't trigger warnings

  • Unrecognized parameters pass through silently

  • No type checking ensures values match expected formats

  • Parameter discovery requires reading the code

    For example, these misspelled parameters won't trigger errors:

sections/broken-section.liquid

{% render 'loading-spinner', produt: product, show_vendorr: true %}

LiquidDoc solves these problems by providing structured documentation that development tools can recognize, offering real-time feedback during development.

Anchor to Syntax referenceSyntax reference

LiquidDoc uses a JSDoc-inspired syntax to document snippets and blocks. The following tags are supported:

Anchor to Basic structureBasic structure

Place LiquidDoc content at the top of a snippet or a block file inside a doc tag:

snippets/example-snippet.liquid

{% doc %}
Provides an example of a snippet description.

@param {string} title - The title to display
@param {number} [max_items] - Optional maximum number of items to show

@example
{% render 'example-snippet', title: 'Featured Products', max_items: 3 %}
{% enddoc %}

Anchor to Descriptions (,[object Object],)Descriptions (@description)

You can document your snippet's or block's purpose in two ways:

snippets/example-snippet.liquid

{% doc %}
The description can be placed before any @ annotations without needing a tag.

@description You can also use this tag to place a description anywhere.
{% enddoc %}

Anchor to Usage notesUsage notes

  • You can omit the @description tag by providing a description before any @ annotations.
  • If you provide multiple descriptions, then only the first one will appear when hovering over a render tag.
  • Multi-line descriptions are automatically formatted to start on a new line.

Anchor to Parameters (,[object Object],)Parameters (@param)

Parameters define the inputs accepted by a snippet or a static block with the following format:

@param {type} name - description

ComponentRequiredDescription
TypeOptionalA data type in curly braces {}. Must be one of the supported types.
NameRequiredA parameter identifier. For optional parameters, wrap in []. For example, [max_items].
DescriptionOptionalAn explanation of the parameter's purpose.

The following example shows how to use parameters:

snippets/param-examples.liquid

{% doc %}
Product card snippet

@param {string} title - Main product title
@param {number} price - Product price value
@param {boolean} show_vendor - Whether to display vendor name
@param {object} product - Product object
@param {string} [subtitle] - Optional secondary text
{% enddoc %}

Anchor to Supported parameter typesSupported parameter types

TypeDescription
stringText values
numberNumeric values
booleanTrue/false values. All values in Liquid have truthy or falsy evaluation.
objectComplex Liquid types or anything that's not a primitive

Anchor to Examples (,[object Object],)Examples (@example)

Examples demonstrate how a snippet or a static block should be used:

snippets/example-snippet.liquid

{% 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 %}

@example
{% render 'price',
price: variant.price,
show_compare_at: false
%}
{% enddoc %}

Anchor to Usage notesUsage notes

  • Multiple examples help demonstrate different usage patterns.
  • Multi-line examples are automatically formatted to start on a new line.

Anchor to Editor featuresEditor features

LiquidDoc speeds up development while catching parameter errors, typos, and type mismatches in real-time.

Anchor to Hover documentationHover documentation

See comprehensive information when hovering over a name in a render tag:

Hovering over 'product-card' to see LiquidDoc documentation

Anchor to Code completionCode completion

Get smart suggestions for parameter names when using documented snippets or static blocks:

Code completion showing available LiquidDoc snippets

Anchor to Parameter validationParameter validation

Receive warnings when required parameters are missing:

Parameter validation showing required parameters for a snippet

Anchor to Type checkingType checking

Get appropriate suggestions and validation based on type annotations in @param tags.

Type checking showing proper value types for parameters

When a type mismatch is detected, the editor suggests converting to these fallback values:

TypeFallback value
string''
number0
booleanfalse
objectN/A

Anchor to Theme CheckTheme Check

LiquidDoc integrates with Theme Check to validate your snippets and blocks through:

  • Documentation checks - Validate syntax and structure inside {% doc %} blocks
  • Usage checks - Ensure {% render %} tags properly use documented parameters

Anchor to Documentation checksDocumentation checks

CheckDescription
UniqueDocParamNamesEach parameter defined in LiquidDoc needs to have a unique name.
UnsupportedDocTagThe doc tag can only be used within a liquid snippet file.
ValidDocParamNamesEach parameter defined in LiquidDoc should not collide with liquid tags and global variables.
ValidDocParamTypesEach parameter defined in LiquidDoc should be string, number, boolean, object, or any liquid object that isn't exclusively a global object.
UnusedDocParamThe parameters defined within the doc tag must be used within the scope of the variable.

Anchor to Usage checksUsage checks

CheckDescription
DuplicateContentForArgumentsEach named argument should be passed into the content_for tag only once.
DuplicateRenderSnippetArgumentsEach named argument should be passed into the render tag only once.
MissingContentForArgumentsWhen you render a static block, you must provide all required arguments defined in that block file's LiquidDoc.
MissingRenderSnippetArgumentsWhen you render a snippet, you must provide all required arguments defined in that snippet file's LiquidDoc.
UnrecognizedContentForArgumentsAll arguments provided when rendering a static block must match the arguments defined in that block's LiquidDoc.
UnrecognizedRenderSnippetArgumentsAll arguments provided when rendering a snippet must match the arguments defined in that snippet's LiquidDoc.
ValidContentForArgumentTypesAll arguments provided when rendering a static block must match the respective parameter's type defined in that block's LiquidDoc.
ValidRenderSnippetArgumentTypesAll arguments provided when rendering a snippet must match the respective parameter's type defined in that snippet's LiquidDoc.
CheckDescription
DuplicateRenderSnippetArgumentsEach named argument should be passed into the render tag only once.
MissingRenderSnippetArgumentsWhen you render a snippet, you must provide all required arguments defined in that snippet file's LiquidDoc.
UnrecognizedRenderSnippetArgumentsAll arguments provided when rendering a snippet must match the arguments defined in that snippet's LiquidDoc.
ValidRenderSnippetArgumentTypesAll arguments provided when rendering a snippet must match the respective parameter's type defined in that snippet's LiquidDoc.

Anchor to LimitationsLimitations

Anchor to Dynamic validationDynamic validation

Usage checks are disabled when the name is a variable:

Anchor to ✗ Disabled✗ Disabled

section-example.liquid

{% assign snippetName = 'price' %}
{% render snippetName %}
Anchor to ✓ Enabled✓ Enabled

section-example.liquid

{% render 'price' %}

Anchor to Dynamic type validationDynamic type validation

We don't currently validate the types of objects or variables passed as parameters:

Anchor to ✗ Disabled✗ Disabled

section-example.liquid

{% render 'price', price: product.price %}
Anchor to ✓ Enabled✓ Enabled

section-example.liquid

{% render 'price', price: 100 %}

Anchor to Next stepsNext steps

Was this page helpful?