Liquid Support

Scriban supports all the core liquid syntax types, operators, tags and filters.

• Known issues
• Supported types
• Supported operators
• Supported tags
  • Variable and properties accessors
  • comment tag
  • raw tag
  • assign tag
  • if tag
  • unless tag
  • case and when tags
  • for tag
  • tablerow tag
  • capture tag
  • Pipe calls
• Supported filters
• Converting liquid to scriban using liquid2scriban

Known issues

NOTE: The liquid syntax has never been strictly formalized, and custom tags implementation can choose whatever syntax for their arguments.

This is a known issue in liquid itself, for example:

• issue 507: Custom tags: what’s the preferred method of providing arguments containing quotes
• issue 671: Using liquid class libraries inside Liquid::Tag
• issue 560: Unified syntax for tag arguments [RFC]

For example in liquid, you usually pass arguments to tags and filters like this (supported by scriban):

{{ "this is a string" | function "arg1" 15 16 }}

{% custom_tag "arg1" 15 16 %}

But some liquid tag/filter implementations may in fact choose to accept different ways of passing arguments:

{% avatar user=author size=24 %}

There is in fact multiple versions of the liquid language, supporting different syntaxes for tags, which are completely arbitrary and not unified.

As a consequence, the liquid parser implemented in Scriban cannot parse any custom liquid tags/filters that are using custom arguments parsing but only regular arguments (strings, numbers, variables, variable properties) separated by spaces.

Supported types

Liquid types are translated to the same types in scriban:

• string
• number
• boolean

The nil value (which can't be expressed in liquid) is equivalent to the expression null in scriban.

• array are also supported, except that scriban allows to create arrays directly from the language unlike liquid

In addition to this, scriban supports the creation of an object

Supported operators

Liquid supports only conditional expressions and they directly translate to conditionnal expressions in scriban.

In addition to this, scriban supports:

• binary operators
• unary operators
• range 1..x expressions
• The null coalescing operator ??

Supported tags

In the following sections, you will find a list of the supported liquid tags and how scriban translates a liquid template into a scriban template.

NOTE: All the following examples are using the feature Ast to text that allowed to translate liquid code into scriban code automatically

Variable and properties accessors

comment tag

Liquid comment/endcomment tags translate to a code block {{ ... }} embracing a multiline comments ##

liquid

This is plain {% comment %}This is comment {% with ## some tag %} and comment{% endcomment %}

scriban

This is plain {{## This is comment {% with \#\# some tag %\} and comment ##}}

raw tag

Liquid raw tag block translate to an escape block

liquid

This is plain {% raw %}This is raw {% with some tag %} and raw{% endraw %}

scriban

This is plain {%{This is raw {% with some tag %} and raw}%}

assign tag

Liquid assign tag translates to a simple assignment expression

liquid

{% assign variable = 1 %}
{{ variable }}

scriban

{{ variable = 1 }}
{{ variable }}

if tag

Liquid if <expression>/endif tags translate to a if <expression>/end

liquid

{% assign variable = 1 %}
{% if variable == 1 %}
  This is a variable with 1
{% endif %}

scriban

{{ variable = 1 }}
{{ if variable == 1 }}
  This is a variable with 1
{{ end }}

unless tag

Liquid unless <expression>/endunless tags translate to a if <expression>/end with a reversed nested !(expression)

liquid

{% assign variable = 1 %}
{% unless variable == 1 %}
  This is not a variable with 1
{% endunless %}

scriban

{{ variable = 1 }}
{{ if!( variable == 1 )}}
  This is not a variable with 1
{{ end }}

case and when tags

Liquid case <variable>/when <expression>/endcase tags translate to a case <expression>/when <expression>/end

liquid

{%- assign variable = 5 -%}
{%- case variable -%}
    {%- when 6 -%}
        Yo 6
    {%- when 7 -%}
        Yo 7
    {%- when 5 -%}
        Yo 5
{% endcase -%}

scriban

{{ variable = 5 -}}
{{ case variable -}}
    {{ when 6 -}}
        Yo 6
    {{- when 7 -}}
        Yo 7
    {{- when 5 -}}
        Yo 5
{{ end }}

for tag

Liquid for <variable> in <expression>/endfor tags translate to the same for/end

liquid

{%- for variable in (1..5) -%}
    This is variable {{variable}}
{% endfor -%}

scriban

{{ for variable in (1..5) -}}
    This is variable {{variable}}
{{ end }}

NOTE: Scriban supports all tags arguments: limit, offset, reversed

tablerow tag

Liquid tablerow <variable> in <expression>/endtablerow tags translate to the same tablerow/end

liquid

{%- tablerow variable in (1..5) -%}
    This is variable {{variable}}
{% endtablerow -%}

scriban

{{ tablerow variable in (1..5) -}}
    This is variable {{variable}}
{{ end }}

NOTE: Scriban supports all tags arguments for tablerow: cols, limit, offset, reversed

capture tag

Liquid capture <variable>/endcapture tags translate to a capture <expression>/end

liquid

{%- capture variable -%}
    This is a capture
{%- endcapture -%}
{{ variable }}

scriban

{{ capture variable -}}
    This is a capture
{{- end -}}
{{ variable }}

Pipe calls

Liquid pipe call translates to the same pipe call

liquid

{% assign test = "abcdef" %}
{{ test | truncate: 5 }}

scriban

{{ test = "abcdef" }}
{{ test |  string.truncate 5 }}

As you can notice, Scriban will translate a call to a liquid tag to the corresponding scriban tag. But scriban also provides supports for direct tags calls using the LiquidTemplateContext. See liquid support in runtime

Supported filters

By default, all liquid filters are translated to scriban builtin functions (through objects like string or array)

The translation is performed by the TryLiquidToScriban function at parsing time.

This translation can be disabled by setting the ParserOptions.LiquidFunctionsToScriban to false

Converting liquid to scriban using liquid2scriban

If you compile this repository, you will find a tool liquid2scriban that allows to convert a liquid script to scriban.

The liquid2scriban has one option that allows to parse Jekyll liquid templates that are passing to the include directive raw strings without quotes (e.g {% include /this/is/partial.html %}) In that case, you can pass the option --relaxed-include to liquid2scriban, to allow the convertor to recognize this parameter as an implicit string instead.