█   █ █▀█ █ █ █ █▀▄   █▀▄ █▀█ █▀▀ █▀▀
 █▄▄ █ ▀▀█ █▄█ █ █▄▀   █▄▀ █▄█ █▄▄ ▄▄█

A parser for Shopify liquid doc tags that allows you to extract the {% doc %} content of a liquid file into an object and check liquid files to make sure they all have a doc block. Written in Rust and compiled to WASM to make it run in node and the browser.

Content

• Goals
• Parser
• Checker
• Contribution
• License

Goals

This project wants to stay as close to, how Shopify interprets the doc tag, as possible. Right now this library supports only what has been noted in the Shopify liquid docs:

• @description, @param and @example
• Description without @description at the top
• Param types: string, string[], number, number[], boolean, boolean[], object and object[]
• Param types also supports Shopify objects via the Shopify type. e.g. { Shopify: "currency" }
• Param optionality
• Param type and description are optional
• Multiple examples

Parser

This library can be used as a library in your or JS/TS (or Rust) project.

To install:

npm i @the-working-party/liquid-docs

const {
	get_files,   // a helper function to get all files from a glob
	parse,       // parse the input of a single file
	parse_files, // parse a list of files
	TwpTypes,    // the parser struct from Rust
} = require("@the-working-party/liquid-docs");

// An example liquid snippet file
const result = parse(`
{%- doc -%}
Renders an image block.

@param {string} [loading] - The html loading attribute
@param {string} alt       - The alt text for the image

@example
{% render 'image',
  loading: 'eager',
%}
{%- enddoc -%}

<image-block
  ratio="{{ block.settings.ratio }}"
  height="{{ block.settings.height }}"
  style="--border-radius: {{ block.settings.border_radius }}px;"
  {{ block.shopify_attributes }}
>
  {{ closest.product.featured_image, loading: loading, alt: alt | default: closest.product.title }}
</image-block>

{% stylesheet %}
...
{% endstylesheet %}

{% schema %}
...
{% endschema %}
`);

console.log(result);
/*
[
  {
    "description": "Renders an image block.",
    "param": [
      {
        "name": "loading",
        "description": "The html loading attribute",
        "type": "String",
        "optional": true
      },
      {
        "name": "alt",
        "description": "The alt text for the image",
        "type": "String",
        "optional": false
      }
    ],
    "example": ["{% render 'image',\n  loading: 'eager',\n%}"]
  }
]
*/

Checker

The checker is a built-in CLI tool that allows you to check every file within a given glob for the existence of doc tags.
The checker will return a non-zero error code if it finds a file that does not contain a doc tag.

$ npm i -g @the-working-party/liquid-docs

Usage:

$ liquid-docs-check "{blocks,snippets}/*.liquid"
Checking files...
✔️ blocks/image_block.liquid
✔️ blocks/cart-drawer.liquid
✔️ snippets/card.liquid

✨ All liquid files (3) have doc tags

Or when it fails:

$ liquid-docs-check "{blocks,snippets}/*.liquid"
Checking files...
✔️ blocks/image_block.liquid
✖️ blocks/cart-drawer.liquid
✔️ snippets/card.liquid

Found 1 liquid file without doc tags

Note

The checker will collect files into 10MB batches to make sure we don't hit WASM limits while still reducing the hops between WASM and JS to a minimum

Theme Size	No Batching	10MB Batch Calls
5MB (small)	2	2
10MB (typical)	2	2
15MB (large)	2	4
50MB (huge)	2 (risky)	10 (safe)
200MB (extreme)	crashes	40 (still works)

Contribution

Most of the logic is kept in the rust code base to keep this library fast and efficient.

Releases

• v3.0.0 - Extracting legal Shopify objects directly from Shopify codebase, renamed Unknown type to Shopify
• v2.0.0 - Added support for unknown types, checker does not error on unknown types anymore
• v1.1.0 - Added support of array types in param
• v1.0.2 - Fixed version display in help and version flag
• v1.0.1 - Fixed tarball wasm inclusion
• v1.0.0 - First release

License

(c) by The Working Party
License MIT