liquidjs/docs/source/tutorials/options.md

title

title
Options

The Liquid constructor accepts a plain object as options to define the behavior of LiquidJS. All of these options are optional thus we can specify any of them, for example the cache option:

const { Liquid } = require('liquidjs')
const engine = new Liquid({
    cache: true
})

{% note info API documentation %} Following is an overview for all the options. For exact types and signatures, see LiquidOptions | API. {% endnote %}

cache

cache is used to improve performance by caching previously parsed template structures, especially in cases when we repeatedly parse or render files.

It defaults to false. When set to true, a default LRU cache of size 1024 will be enabled. It can also be a number indicating the cache size you want.

Additionally, it can also be a custom cache implementation. See Caching for details.

Partials/Layouts

root is used to specify template directories for LiquidJS to look up and read template files. Can be a single string or an array of strings. See Render Files for details.

layouts is used to specify template directories for LiquidJS to look up files for {% layout %}. Same format as root and will default to root if not specified.

partials is used to specify template directories for LiquidJS to look up files for {% render %} and {% include %}. Same format as root and will default to root if not specified.

relativeReference is set to true by default to allow relative filenames. Note that relatively referenced files also need to be within the corresponding root. For example you can reference another file like {% render ../foo/bar %} as long as ../foo/bar is also within partials directory.

dynamicPartials

Note: for historical reasons, it's named dynamicPartials but it also works for layouts.

dynamicPartials indicates whether or not to treat filename arguments in include, render, layout tags as a variable. Defaults to true. For example, render the following snippet with scope { file: 'foo.html' } will include the foo.html:

{% include file %}

Setting dynamicPartials: false, LiquidJS will try to include the file named file, which is weird but allows simpler syntax if your template relations are static:

{% liquid foo.html %}

{% note warn Common Pitfall %} LiquidJS defaults this option to true to be compatible with shopify/liquid, but if you're from eleventy it's set to false by default (see Quoted Include Paths) which I believe is trying to be compatible with Jekyll.{% endnote %}

Jekyll include

{% since %}v9.33.0{% endsince %}

jekyllInclude is used to enable Jekyll-like include syntax. Defaults to false, when set to true:

• Filename will be static: dynamicPartials now defaults to false (instead of true). And you can set dynamicPartials back to true.
• Use = instead of : to separate parameter key-values.
• Parameters are under include variable instead of current scope.

For example in the following template, name.html is not quoted, header and "HEADER" are separated by =, and the header parameter is referenced by include.header. For more details, see include.

// entry template
{% include article.html header="HEADER" content="CONTENT" %}

// article.html
<article>
  <header>{{include.header}}</header>
  {{include.content}}
</article>

extname

extname defines the default extension name to be appended into filenames if the filename has no extension name. Defaults to '' which means it's disabled by default. By setting it to .liquid:

{% render "foo" %}  there's no extname, adds `.liquid` and loads foo.liquid
{% render "foo.html" %}  there is an extname already, loads foo.html directly

{% note info Legacy Versions %} Before 2.0.1, extname is set to .liquid by default. To change that you need to set extname: '' explicitly. See #41 for details. {% endnote %}

fs

fs is used to define a custom file system implementation which will be used by LiquidJS to look up and read template files. See Abstract File System for details.

globals

globals is used to define global variables available to all templates even in cases of render tag. See 3185 for details.

jsTruthy

jsTruthy is used to use standard JavaScript truthiness rather than Shopify's.

It defaults to false. For example, when set to true, a blank string would evaluate to false with jsTruthy. With Shopify's truthiness, a blank string is true.

outputEscape

outputEscape can be used to automatically escape output strings. It can be one of "escape", "json", or (val: unknown) => string, defaults to undefined.

• For untrusted output variables, set outputEscape: "escape" makes them be HTML escaped by default. You'll need raw filter for direct output.
• "json" is useful when you're using LiquidJS to create valid JSON files.
• It can even be a function that allows you to control what variables are output throughout LiquidJS. Please note the input can be any type other than string, e.g. a filter may return a non-string value.

Date

timezoneOffset is used to specify a different timezone to output dates, your local timezone will be used if not specified. For example, set timezoneOffset: 0 to output all dates in UTC/GMT 00:00.

preserveTimezones is a boolean that affects only literal timestamps. When set to true, all literal timestamps will remain the same when output. This is a parser option, so Date objects passed to LiquidJS as data will not be affected. Note that preserveTimezones has a higher priority than timezoneOffset.

dateFormat is used to specify a default format to output dates. %A, %B %-e, %Y at %-l:%M %P %z will be used if not specified. For example, set dateFormat: %Y-%m-%dT%H:%M:%S:%LZ to output all dates in JavaScript Date.toJson() format.

Trimming

greedy, trimOutputLeft, trimOutputRight, trimTagLeft, trimTagRight options are used to eliminate extra newlines and indents in templates around Liquid Constructs. See Whitespace Control for details.

Delimiter

outputDelimiterLeft, outputDelimiterRight, tagDelimiterLeft, tagDelimiterRight are used to customize the delimiters for LiquidJS Tags and Filters. For example with outputDelimiterLeft: <%=, outputDelimiterRight: %> we are able to avoid conflicts with other languages:

<%= username | append: ", welcome to LiquidJS!" %>

Strict

strictFilters is used to assert filter existence. If set to false, undefined filters will be skipped. Otherwise, undefined filters will cause a parse exception. Defaults to false.

strictVariables is used to assert variable existence. If set to false, undefined variables will be rendered as empty string. Otherwise, undefined variables will cause a render exception. Defaults to false.

lenientIf modifies the behavior of strictVariables to allow handling optional variables. If set to true, an undefined variable will not cause an exception in the following two situations: a) it is the condition to an if, elsif, or unless tag; b) it occurs right before a default filter. Irrelevant if strictVariables is not set. Defaults to false.

ownPropertyOnly limits template property reads on plain scope objects to own properties. Defaults to true. See Security Model.

{% note info Nonexistent Tags %} Nonexistent tags always throw errors during parsing and this behavior cannot be customized. {% endnote %}

Parameter Order

Parameter orders are ignored by default, for example {% for i in (1..8) reversed limit:3 %} will always perform limit before reversed, even if reversed occurs before limit. To make parameter order respected, set orderedFilterParameters to true. Its default value is false.