metais help templates
Writing templates: the environment, every filter, and escaping.
A template is Liquid, in the dialect spec chapter 7 pins. The examples on this
page read these inputs:
inputs.rows [{"name": "b", "n": 2, "tag": "new"}, {"name": "a", "n": 1,
"tag": null}]
inputs.note "line 1\nline 2"
inputs.title null: declared by the schema, and not supplied
A loop over an input, with forloop:
{% for row in inputs.rows -%}
{{ forloop.index }} of {{ forloop.length }}: {{ row.name }}
{% endfor -%}
gives
1 of 2: b
2 of 2: a
assign, a filter chain, and a test for nil:
{% assign names = inputs.rows | map: "name" | sort -%}
{% if inputs.title %}{{ inputs.title }}{% else %}Untitled{% endif %}
{{ names | join: ", " }}
gives
Untitled
a, b
A partial, rendered once per element:
templates/row.md holds
- {{ row.name }} ({{ row.n }})
and the template
{% render "row.md" for inputs.rows as row %}
gives
- b (2)
- a (1)
The environment:
inputs One member per declared input: its validated value, defaults applied.
An optional input not supplied is nil.
package The manifest's metais, name, version, title, description, guide,
authors, license and homepage, and digest, the package digest.
output In a template body: path, the output's path, and root, the relative
prefix from its directory to the root of its tree ("", "../", ...).
now The render time the caller supplied, in UTC (2026-10-18T09:30:00Z),
or nil. It is a template's only clock.
sources Where each input came from: origin is file, command-line or default;
for a collection, each item's file name, stem and form.
item In an output with for_each only: the element being rendered.
fan_out Beside item: index, index0, rindex, rindex0, first, last, length,
previous and next.
Names are strict. A name nothing binds is an error
(template.undefined_variable), and so is a property the schema does not declare
and the data does not hold (template.undefined_property), never an empty string.
A property the schema declares and the data omits is nil, and nil writes
nothing. Reading a property of nil is an error (template.nil_property), whatever
filter follows, default included; {% if a and a.b %} reads safely. Only nil and
false are false: 0, "", [] and {} are true, so {% if inputs.x %} asks whether x
was supplied. x == empty holds for an empty string, array or object; x == blank
also for nil, false and whitespace.
for loops over an array, a range (1..3) or an object, whose members it visits in
name order as [name, value] pairs; it takes limit:, offset: and reversed, and
else for an empty collection, and break and continue. Inside it, forloop has
index and index0 (from 1 and 0), rindex and rindex0 (from the end), first, last,
length, parentloop and name. {%- and -%} remove the whitespace before and after
a tag; nothing else is trimmed, so a tag alone on its line leaves its line feed.
assign binds a value and capture binds the text its block writes, for the rest
of the template; neither may take a global's name, forloop or tablerowloop
(template.reserved_name).
render "<path>" renders a partial: a template under templates/, named by its
full path there as a string literal ("parts/row.md"). It takes k: v parameters,
with x [as n], or for xs [as n], which renders it once per element and binds
forloop. A partial sees its parameters, its own bindings and the globals, and
none of its caller's assign, capture or loop variables. include is refused.
METAIS adds three tags, whose text is never escaped:
embed {% embed "<input>" %} writes an input's bytes exactly as its
data-directory file holds them; index: n names an item of a
collection.
asset {% asset "<path>" %} writes the relative path from the file being
rendered to where the render copies an asset under assets/; as:
"contents" writes its text, as: "base64" its bytes.
provenance {% provenance all %} writes one comment line naming the package,
its version and digest, the inputs' digests, the tool and the
render time when one was given; name parts to write fewer.
Filters:
Every filter of the dialect, with an example and what it gives. A filter's
keyword argument follows its positional ones: csv: "name", delimiter: ";". In
what an example gives, \n is a line feed.
Strings:
append Adds text at the end. {{ "doc" | append: ".md" }} gives doc.md
prepend Adds text at the start. {{ "md" | prepend: "." }} gives .md
capitalize Upper-cases the first character and lower-cases the rest.
{{ "hELLO" | capitalize }} gives Hello
downcase Lower-cases every letter, by Unicode's simple case mapping.
{{ "AbC" | downcase }} gives abc
upcase Upper-cases every letter, by Unicode's simple case mapping.
{{ "abc" | upcase }} gives ABC
strip Removes the whitespace at both ends.
{{ " a b " | strip }} gives a b
lstrip Removes the whitespace at the start.
{{ " a " | lstrip | append: "]" }} gives a ]
rstrip Removes the whitespace at the end.
{{ " a " | rstrip | prepend: "[" }} gives [ a
squish Strips both ends and makes each run of whitespace one space.
{{ inputs.note | squish }} gives line 1 line 2
strip_html Removes HTML tags.
{{ "<b>bold</b> text" | strip_html }} gives bold text
strip_newlines Removes every line break.
{{ inputs.note | strip_newlines }} gives line 1line 2
newline_to_br Writes <br /> before each line break.
{{ inputs.note | newline_to_br }} gives line 1<br />\nline 2
remove Removes every occurrence of a text.
{{ "a-b-c" | remove: "-" }} gives abc
remove_first Removes the first occurrence.
{{ "a-b-c" | remove_first: "-" }} gives ab-c
remove_last Removes the last occurrence.
{{ "a-b-c" | remove_last: "-" }} gives a-bc
replace Replaces every occurrence of a text with another.
{{ "a-b-c" | replace: "-", "+" }} gives a+b+c
replace_first Replaces the first occurrence.
{{ "a-b-c" | replace_first: "-", "+" }} gives a+b-c
replace_last Replaces the last occurrence.
{{ "a-b-c" | replace_last: "-", "+" }} gives a-b+c
split Splits a string into an array at each separator.
{{ "a,b,c" | split: "," | join: " " }} gives a b c
truncate Cuts a string to a number of characters, the ellipsis (...
unless given) included.
{{ "abcdefgh" | truncate: 6 }} gives abc...
truncatewords Keeps a number of words, then the ellipsis (... unless given).
{{ "one two three" | truncatewords: 2 }} gives one two...
Numbers (integers give an integer):
abs The absolute value. {{ -3 | abs }} gives 3
ceil Rounds up to an integer. {{ 1.2 | ceil }} gives 2
floor Rounds down to an integer. {{ 1.8 | floor }} gives 1
round Rounds half away from zero, to a number of decimal places when
given. {{ 2.5 | round }} gives 3
plus Adds; a float adds as the decimal it is written as.
{{ 0.1 | plus: 0.2 }} gives 0.3
minus Subtracts. {{ 5 | minus: 7 }} gives -2
times Multiplies. {{ 3 | times: 1.5 }} gives 4.5
divided_by Divides; two integers give the quotient rounded down.
{{ 7 | divided_by: 2 }} gives 3
modulo The remainder of the division rounded down.
{{ -7 | modulo: 2 }} gives 1
at_least The larger of the value and the argument.
{{ 3 | at_least: 5 }} gives 5
at_most The smaller of the value and the argument.
{{ 3 | at_most: 2 }} gives 2
Arrays:
size The length of a string, array or object; 0 for a number, a
boolean and nil. {{ "abc" | size }} gives 3
first The first element. {{ "a,b,c" | split: "," | first }} gives a
last The last element. {{ "a,b,c" | split: "," | last }} gives c
join The elements' texts, with a separator between them (a space
unless given).
{{ "a,b" | split: "," | join: " + " }} gives a + b
reverse The elements in reverse order.
{{ "a,b,c" | split: "," | reverse | join: "," }} gives c,b,a
concat The elements of both arrays.
{{ (1..2) | concat: (3..4) | join: "," }} gives 1,2,3,4
compact Drops nil elements, or the elements whose property is nil.
{{ inputs.rows | map: "tag" | compact | join: "," }} gives new
uniq Drops repeated elements.
{{ "a,b,a" | split: "," | uniq | join: "," }} gives a,b
map Each element's property.
{{ inputs.rows | map: "name" | join: "," }} gives b,a
sort Sorts, by a property when given.
{{ inputs.rows | sort: "n" | map: "name" | join: "," }}
gives a,b
sort_natural Sorts ignoring case.
{{ "b,C,a" | split: "," | sort_natural | join: "," }}
gives a,b,C
slice The element or character at an offset, or as many as a length
gives. {{ "abcdef" | slice: 1, 3 }} gives bcd
sum Adds the elements, or their property.
{{ inputs.rows | sum: "n" }} gives 3
where Keeps the elements whose property is truthy, or equals a
value.
{{ inputs.rows | where: "n", 1 | map: "name" | join }} gives a
reject Drops the elements whose property is truthy, or equals a
value.
{{ inputs.rows | reject: "tag" | map: "name" | join }} gives a
has Whether an element's property is truthy, or equals a value.
{{ inputs.rows | has: "name", "a" }} gives true
find The first element whose property is truthy, or equals a value.
{{ inputs.rows | find: "n", 1 | json }}
gives {"n":1,"name":"a","tag":null}
find_index The position of that element, from 0.
{{ inputs.rows | find_index: "name", "a" }} gives 1
default The value, or its argument when the value is nil, false, or an
empty string, array or object; allow_false: true keeps false.
{{ inputs.title | default: "Untitled" }} gives Untitled
Encoding (escape, h and escape_once give a safe value):
escape Writes & < > " and ' as HTML character references.
{{ "a < b" | escape }} gives a < b
h escape, by another name. {{ "a & b" | h }} gives a & b
escape_once escape, but leaves an & that already begins a character
reference.
{{ "< & <" | escape_once }} gives < & <
url_encode Percent-encodes a URL component; a space is +.
{{ "a b&c" | url_encode }} gives a+b%26c
url_decode Decodes what url_encode writes.
{{ "a+b%26c" | url_decode }} gives a b&c
base64_encode Base64. {{ "hi?" | base64_encode }} gives aGk/
base64_decode Decodes base64. {{ "aGk/" | base64_decode }} gives hi?
base64_url_safe_encode
Base64 with - and _ for + and /.
{{ "hi?" | base64_url_safe_encode }} gives aGk_
base64_url_safe_decode
Decodes URL-safe base64.
{{ "aGk_" | base64_url_safe_decode }} gives hi?
METAIS's own (spec chapter 8):
json RFC 8785 JSON: members in name order, no whitespace; indent: n
(1 to 8) pretty-prints.
{{ inputs.rows | last | json }}
gives {"n":1,"name":"a","tag":null}
yaml A YAML block document, members in name order, with no final
line feed; a string YAML could read otherwise, such as n, is
quoted.
{{ inputs.rows | first | yaml }}
gives "n": 2\nname: b\ntag: new
csv An array of objects as CSV, of the columns named or else every
member; header: false, headers: and delimiter: change it.
{{ inputs.rows | csv: "name", "n" }} gives name,n\nb,2\na,1\n
markdown_table An array of objects as a Markdown table, with the columns and
headers: of csv.
{{ inputs.rows | markdown_table: "name", "n" }}
gives | name | n |\n| --- | --- |\n| b | 2 |\n| a | 1 |\n
json_script json for a <script> element: < > & U+2028 and U+2029 written
as \u escapes; safe.
{{ "a&b" | json_script }} gives "a\u0026b"
safe Marks a value safe from escaping; only as the last filter of
{{ }} or echo. {{ "<b>" | safe }} gives <b>
slug Lower-case ASCII letters and digits joined by -; accents are
dropped, and a string with no slug is an error.
{{ "Hello, World!" | slug }} gives hello-world
Values for readers (spec chapter 8); none reads a locale:
date {{ "2026-10-18T09:30:00+02:00" | date: "%Y-%m-%d %H:%M %z" }}
gives 2026-10-18 09:30 +0200
Formats an RFC 3339 date or date-time, or Unix seconds, in its
own offset, with a strftime format; spec chapter 8 lists the
directives.
number {{ 48920000 | number: decimals: 2, group: "," }}
gives 48,920,000.00
Writes a number, or a decimal text such as "-1234.50" at any
length, for a reader. decimals: (0 to 20) rounds half away
from zero; group: and point: name the separators, and with
none named it groups nothing and writes . as the point.
amount {{ 48920000 | amount: "EUR", group: "," }}
gives EUR 48,920,000.00
Writes an amount with its ISO 4217 code, usually an input, so
one template writes any currency: its decimals follow the code
by spec Appendix C unless decimals: gives them, it takes
number's group: and point:, and code: "after" writes the code
last. It writes no symbol.
There is no money filter: amount takes the amount in the
currency's major unit, euros and not cents, so an amount in
cents is divided by 100 first.
duration {{ "00:07:25" | duration: "%-H h %M min", fields: "d:h:m" }}
gives 7 h 25 min
Writes a length of time: whole seconds, an ISO 8601 duration
such as PT7H25M, or fields separated by : that fields: names
("d:h:m", "h:m:s" and the like). Its directives mirror date's:
%d, %H, %M and %S are days, hours, minutes and seconds, with
date's flags -, _ and 0, and the largest named takes the rest.
Escaping:
An output's escape is none, the default, or html, set in metais.yaml beside its
template (escape: html); nothing is escaped unless it is set. In an html output,
the text of every value {{ }}, echo or cycle writes has & < > " and ' written as
character references; the template's own text, and what raw, embed, asset and
provenance write, are never escaped. A value is safe, and written as it is, when
its last filter is safe, escape, escape_once or json_script, or it is a capture
made in an html output. Safety does not pass through a later filter. A partial
is escaped as the output it renders into is.
Escaping does not make text safe inside a <script> element or a URL: data in a
<script> element goes through json_script, whose text can neither close the
element nor open an HTML comment, and a URL component through url_encode; the
dialect offers nothing else for those contexts. In an html output:
<p>{{ "Fish & <Chips>" }}</p>
gives
<p>Fish & <Chips></p>
{{ "<b>bold</b>" | safe }} {{ "<b>" | escape }}
gives
<b>bold</b> <b>
{{ inputs.note | escape | newline_to_br | safe }}
gives
line 1<br />
line 2
<a href="/find?q={{ "a b&c" | url_encode }}">
gives
<a href="/find?q=a+b%26c">
<script type="application/json">{{ "a</script>" | json_script }}</script>
gives
<script type="application/json">"a\u003c/script\u003e"</script>
'metais help manifest' gives the fields of metais.yaml; spec chapters 7, 8 and 9
give the environment, the filters and tags, and the outputs in full.