---
title: LiquidDoc
description: >-
  Explore and understand Liquid documentation with LiquidDoc, a tool for Shopify
  theme developers.
---

LiquidDoc gives you a way to create a structured interface for Liquid snippets<If featureFlag="dev_tools_liquiddoc_v2"> and blocks</If>, 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.

## 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:

<CodeBlock type="file" title="sections/broken-section.liquid">
  ```liquid
  {% render 'loading-spinner', produt: product, show_vendorr: true %}
  ```
</CodeBlock>

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

## Syntax reference

LiquidDoc uses a JSDoc-inspired syntax to document snippets<If featureFlag="dev_tools_liquiddoc_v2"> and blocks</If>. The following tags are supported:

- [@description](#descriptions-description) - explains the purpose
- [@param](#parameters-param) - documents expected parameters
- [@example](#examples-example) - shows usage examples

### Basic structure

Place LiquidDoc content at the top of a snippet<If featureFlag="dev_tools_liquiddoc_v2"> or a block</If> file inside a `doc` tag:

<CodeBlock type="file" title="snippets/example-snippet.liquid">
  ```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 %}
  ```
</CodeBlock>

### Descriptions (`@description`)

You can document your snippet's<If featureFlag="dev_tools_liquiddoc_v2"> or block's</If> purpose in two ways:

<CodeBlock type="file" title="snippets/example-snippet.liquid">
  ```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 %}
  ```
</CodeBlock>

#### Usage 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.

### Parameters (`@param`)

Parameters define the inputs accepted by a snippet<If featureFlag="dev_tools_liquiddoc_v2"> or a static block</If> with the following format:

`@param {type} name - description`

| Component | Required | Description |
|-----------|----------|-------------|
| **Type** | Optional | A data type in curly braces `{}`. Must be one of the [supported types](#supported-parameter-types). |
| **Name** | Required | A parameter identifier. For optional parameters, wrap in `[]`. For example, `[max_items]`. |
| **Description** | Optional | An explanation of the parameter's purpose. |

The following example shows how to use parameters:

<CodeBlock type="file" title="snippets/param-examples.liquid">
  ```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 %}
  ```
</CodeBlock>

#### Supported parameter types

| Type | Description |
|------|-------------|
| `string` | Text values |
| `number` | Numeric values |
| `boolean` | True/false values. All values in Liquid have truthy or falsy evaluation. |
| `object` | Complex Liquid types or anything that's not a primitive |

### Examples (`@example`)

Examples demonstrate how a snippet<If featureFlag="dev_tools_liquiddoc_v2"> or a static block</If> should be used:

<CodeBlock type="file" title="snippets/example-snippet.liquid">
  ```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 %}
  ```
</CodeBlock>

#### Usage notes

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

## Editor features

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

### Hover documentation

See comprehensive information when hovering over a name in a render tag:
<img src="/content-v2/assets/images/themes/liquid-doc/hover.gif" alt="Hovering over 'product-card' to see LiquidDoc documentation" />

### Code completion

Get smart suggestions for parameter names when using documented snippets<If featureFlag="dev_tools_liquiddoc_v2"> or static blocks</If>:
<img src="/content-v2/assets/images/themes/liquid-doc/completion.gif" alt="Code completion showing available LiquidDoc snippets" />

### Parameter validation

Receive warnings when required parameters are missing:
<img src="/content-v2/assets/images/themes/liquid-doc/param-check.gif" alt="Parameter validation showing required parameters for a snippet" />

### Type checking

Get appropriate suggestions and validation based on type annotations in `@param` tags.
<img src="/content-v2/assets/images/themes/liquid-doc/type-check.gif" alt="Type checking showing proper value types for parameters" />

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

| Type | Fallback value |
|------|----------------|
| `string` | `''` |
| `number` | `0` |
| `boolean` | `false` |
| `object` | `N/A` |

### Theme Check

LiquidDoc integrates with [Theme Check](/docs/storefronts/themes/tools/theme-check) to validate your snippets<If featureFlag="dev_tools_liquiddoc_v2"> and blocks</If> through:

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

#### Documentation checks

| Check | Description |
|-------|------|
| [UniqueDocParamNames](/docs/storefronts/themes/tools/theme-check/checks/unique-doc-param-names) | Each parameter defined in LiquidDoc needs to have a unique name. |
| [UnsupportedDocTag](/docs/storefronts/themes/tools/theme-check/checks/unsupported-doc-tag) | The `doc` tag can only be used within a liquid snippet file. |
| [ValidDocParamTypes](/docs/storefronts/themes/tools/theme-check/checks/valid-doc-param-types) | Each parameter defined in LiquidDoc should be `string`, `number`, `boolean`, `object`, or any [liquid object](https://shopify.dev/docs/api/liquid/objects) that isn't exclusively a global object. |
| [UnusedDocParam](/docs/storefronts/themes/tools/theme-check/checks/unused-doc-param) | The parameters defined within the `doc` tag must be used within the scope of the variable. |

#### Usage checks

<If featureFlag="dev_tools_liquiddoc_v2">
| Check | Description |
|-------|------|
| [DuplicateContentForArguments](/docs/storefronts/themes/tools/theme-check/checks/duplicate-content-for-arguments) | Each named argument should be passed into the `content_for` tag only once. |
| [DuplicateRenderSnippetArguments](/docs/storefronts/themes/tools/theme-check/checks/duplicate-render-snippet-arguments) | Each named argument should be passed into the `render` tag only once. |
| [MissingContentForArguments](/docs/storefronts/themes/tools/theme-check/checks/missing-content-for-arguments) | When you render a static block, you must provide all required arguments defined in that block file's LiquidDoc. |
| [MissingRenderSnippetArguments](/docs/storefronts/themes/tools/theme-check/checks/missing-render-snippet-arguments) | When you render a snippet, you must provide all required arguments defined in that snippet file's LiquidDoc. |
| [UnrecognizedContentForArguments](/docs/storefronts/themes/tools/theme-check/checks/unrecognized-content-for-arguments) | All arguments provided when rendering a static block must match the arguments defined in that block's LiquidDoc. |
| [UnrecognizedRenderSnippetArguments](/docs/storefronts/themes/tools/theme-check/checks/unrecognized-render-snippet-arguments) | All arguments provided when rendering a snippet must match the arguments defined in that snippet's LiquidDoc. |
| [ValidContentForArgumentTypes](/docs/storefronts/themes/tools/theme-check/checks/valid-content-for-argument-types) | All arguments provided when rendering a static block must match the respective parameter's type defined in that block's LiquidDoc. |
| [ValidRenderSnippetArgumentTypes](/docs/storefronts/themes/tools/theme-check/checks/valid-render-snippet-argument-types) | All arguments provided when rendering a snippet must match the respective parameter's type defined in that snippet's LiquidDoc. |
</If><If featureFlagDisabled="dev_tools_liquiddoc_v2">
| Check | Description |
|-------|------|
| [DuplicateRenderSnippetArguments](/docs/storefronts/themes/tools/theme-check/checks/duplicate-render-snippet-arguments) | Each named argument should be passed into the `render` tag only once. |
| [MissingRenderSnippetArguments](/docs/storefronts/themes/tools/theme-check/checks/missing-render-snippet-arguments) | When you render a snippet, you must provide all required arguments defined in that snippet file's LiquidDoc. |
| [UnrecognizedRenderSnippetArguments](/docs/storefronts/themes/tools/theme-check/checks/unrecognized-render-snippet-arguments) | All arguments provided when rendering a snippet must match the arguments defined in that snippet's LiquidDoc. |
| [ValidRenderSnippetArgumentTypes](/docs/storefronts/themes/tools/theme-check/checks/valid-render-snippet-argument-types) | All arguments provided when rendering a snippet must match the respective parameter's type defined in that snippet's LiquidDoc. |
</If>

### Limitations

#### Dynamic validation

Usage checks are disabled when the name is a variable:

##### ✗ Disabled
<CodeBlock type="file" title="section-example.liquid">
  ```liquid
  {% assign snippetName = 'price' %}
  {% render snippetName %}
  ```
</CodeBlock>

##### ✓ Enabled
<CodeBlock type="file" title="section-example.liquid">
  ```liquid
  {% render 'price' %}
  ```
</CodeBlock>

#### Dynamic type validation

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

##### ✗ Disabled
<CodeBlock type="file" title="section-example.liquid">
  ```liquid
  {% render 'price', price: product.price %}
  ```
</CodeBlock>

##### ✓ Enabled
<CodeBlock type="file" title="section-example.liquid">
  ```liquid
  {% render 'price', price: 100 %}
  ```
</CodeBlock>

## Next steps

- [Learn more about Liquid syntax](/docs/api/liquid).
- [Explore theme development best practices](/docs/storefronts/themes/best-practices).