Liquid - Tags: doc
doc
The doc tag lets you write structured inline documentation for partials. Content inside {% doc %}...{% enddoc %} is never rendered — it is read only by platformOS Check and editor tooling (such as the platformOS Check VS Code extension).
Place the doc block at the top of a partial file:
{% doc %}
Renders a product card.
@param {string} title - The product title
@param {number} price - The product price
@param {boolean} [show_vendor] - Optional. Whether to display the vendor name
{% enddoc %}
<div class="card">
<h2>{{ title }}</h2>
<p>{{ price }}</p>
</div>
Why use doc?
Without documentation, common mistakes go undetected:
- Missing required parameters pass silently
- Misspelled parameter names are not caught
- No type checking is applied
- Discovering available parameters requires reading the full partial
The doc tag solves these problems by giving platformOS Check a formal description it can validate at development time.
Syntax
Basic structure
{% doc %}
Optional description of the partial's purpose.
@param {type} name - description
@param {type} [optional_name] - description
@example
{% render 'my-partial', name: 'Alice', count: 3 %}
{% enddoc %}
Descriptions
Write a plain-text description before any @ annotations. You can also use @description anywhere in the block:
{% doc %}
Renders a user avatar with an optional fallback image.
@description You can also place a description with this tag.
@param {string} url - The avatar image URL
{% enddoc %}
If multiple descriptions are provided, only the first one is shown in hover tooltips.
Parameters (@param)
Declare each parameter the partial accepts:
@param {type} name - description
@param {type} [optional_name] - description
| Component | Required | Details |
|---|---|---|
{type} |
Optional | One of the supported types. |
name |
Required | The parameter name. Wrap in [] to mark as optional. |
description |
Optional | A short explanation after -. |
Supported parameter types
| Type | Description |
|---|---|
array |
A generic type used to represent an array of any values. |
boolean |
A |
date |
A date, such as the value |
number |
A numeric value, whole or fractional. |
object |
A generic type used to represent any liquid object or primitive value. |
string |
A text value. |
time |
A point in time, such as the value |
This table is the platform's own type vocabulary, published as liquid_doc.json and read by platformOS Check — so a type listed here is a type it accepts, and the two cannot disagree.
The name of an object from the platformOS objects reference is also a valid type, for example @param {page} current_page or @param {current_user} author. The exceptions are the objects the platform supplies to a file directly, which are never passed as arguments: context (in scope everywhere), content_for_layout (layouts only), and data and response (api_calls only).
Arrays
Add a [] suffix to any type to describe an array whose items are all of that type:
{% doc %}
@param {string[]} tags - A list of tag names
@param {number[]} ids - A list of numeric ids
@param {object[]} records - A list of records
{% enddoc %}
Use the bare array type when the items are of mixed or unknown types:
{% doc %}
@param {array} rows - Rows of arbitrary shape
{% enddoc %}
object also accepts an array value, since it stands for anything that is not a primitive. Prefer array or a [] suffix when you know the argument is a list — it documents the contract more precisely and lets platformOS Check catch a non-list being passed.
Required vs optional parameters
A parameter without brackets is required — platformOS Check reports an error if it is not passed at the call site:
{% doc %}
@param {string} title - Required: must always be passed
@param {string} [subtitle] - Optional: may be omitted
{% enddoc %}
Calling the partial:
{% comment %}OK — title is provided{% endcomment %}
{% render 'card', title: 'Hello' %}
{% comment %}Error — required param 'title' is missing{% endcomment %}
{% render 'card', subtitle: 'World' %}
Examples (@example)
Show one or more usage examples. Multiple @example blocks are supported:
{% doc %}
Price display partial.
@param {number} price - Price value in cents
@param {boolean} [show_compare_at] - Whether to show the compare-at price
@example
{% render 'price', price: product.price %}
@example
{% render 'price', price: variant.price, show_compare_at: true %}
{% enddoc %}
Full example
{% doc %}
Renders a product card with title, price, and optional vendor.
@param {string} title - The product title
@param {number} price - The product price
@param {object} product - The full product object
@param {boolean} [show_vendor] - Whether to show the vendor name
@param {string} [badge_text] - Optional badge label
@example
{% render 'product/card',
title: product.title,
price: product.price,
product: product,
show_vendor: true
%}
{% enddoc %}
<div class="product-card">
<h2>{{ title }}</h2>
{% if badge_text != blank %}
<span class="badge">{{ badge_text }}</span>
{% endif %}
<p class="price">{{ price | money }}</p>
{% if show_vendor %}
<p class="vendor">{{ product.vendor }}</p>
{% endif %}
</div>
Editor features
When the doc tag is present, the platformOS Check VS Code extension provides:
- Hover documentation — see parameter descriptions when hovering over a
{% render %}call - Code completion — autocomplete parameter names at the call site
- Parameter validation — warnings for missing required parameters and unrecognized argument names
- Type checking — suggestions and warnings when literal values don't match the declared type
Limitations
Dynamic partial names
Validation is disabled when the partial name is a variable:
{% comment %}Validation disabled — dynamic name{% endcomment %}
{% assign partial = 'product/card' %}
{% render partial, title: product.title %}
{% comment %}Validation enabled — hardcoded name{% endcomment %}
{% render 'product/card', title: product.title %}
Variable type checking
Type checking is only applied to literal values ("string", 42, true). Variables are not statically type-checked:
{% comment %}Not type-checked — price is a variable{% endcomment %}
{% render 'price', price: product.price %}
{% comment %}Type-checked — 100 is a literal number{% endcomment %}
{% render 'price', price: 100 %}
Related platformOS Check rules
The following checks enforce correct usage of the doc tag:
| Check | Description |
|---|---|
| UniqueDocParamNames | Each @param name must be unique within a doc block |
| ValidDocParamTypes | @param type annotations must be valid platformOS types |
| UnusedDocParam | Declared @param entries must be used in the partial body |
| MissingRenderPartialArguments | Required @param arguments must be provided at the call site |
| UnrecognizedRenderPartialArguments | Arguments at the call site must match declared @param names |
| ValidRenderPartialArgumentTypes | Argument types at the call site must match declared @param types |