ReferenceReference

Liquid filters and tags

Every Liquid filter and tag Douze adds to Fluid, with its arguments, result and an example.

Douze renders templates with Fluid, a .NET implementation of Liquid. Every standard Liquid tag and filter works as Fluid implements it: if, for, assign, capture, include, render, raw, date, map, where, sort, join, replace, size, default and the others. See Fluid's documentation for those. This page lists what Douze adds or changes.

The values templates see are on the template data page. include and render load files from the includes folder, with .liquid as the default extension.

FiltersLink to this heading

Filter Group Result
slug Text A url-safe slug.
markdownify Markdown Markdown as HTML.
strip_markdown Markdown The text of Markdown.
excerpt Markdown The first paragraph, or what comes before <!-- more -->, as HTML.
where_exp Data The items for which an expression is true.
group_by_exp Data The items grouped by the value of an expression.
sort_by Data The items sorted by the value at a path.
index_by Data An object of the items by the value at a path.
json, jsonify Data The value as JSON.
where, find_index, slice Data Fluid's filters, faster on large data arrays.
xml_escape Output The text with XML entities.
absolute_url Output site.url followed by the url.
relative_url Output The url from the root of the server.
strip_html Output The text without tags.
date_to_xmlschema Output An ISO 8601 date.
date_to_rfc822 Output An RFC 822 date.
toc Headings The table of contents as nested lists.
t Locales A UI string in the page's locale.
locale_url Locales A url in another locale.
locale_of Locales The locale of a url.
locale_pages Locales Every page of every locale.
previous_item Collections The item before a page in a collection.
next_item Collections The item after a page in a collection.
nav_active Navigation The sidebar with the current item marked.
nav_prev_next Navigation The previous and next items.
nav_breadcrumbs Navigation The items from the top to the current one.
nav_flatten Navigation The leaves of the sidebar in order.
nav_section Navigation The top-level item that contains a url.
nav_label Navigation The label of an item in a locale.
image_url Images The url of one variant of an image.
image_size Images The width and height of an image.
social_image_url Images The url of the page's social image.

slugLink to this heading

{{ "Héllo, World! 2" | slug }}

hello-world-2: lowercase, diacritics removed, letters, digits, -, _ and ~ kept, any other character a dash, runs of dashes collapsed, dashes, underscores and dots trimmed from the ends, at most 1000 characters. Letters of other scripts are kept.

markdownifyLink to this heading

{{ page.summary | markdownify }}
{{ "**a** b" | markdownify: inline: true }}

Renders a string as Markdown to HTML with the site's pipeline (the markdown section of douze.yml). With inline: true, a single paragraph is returned without its <p>: <strong>a</strong> b. Nil is an empty string.

strip_markdownLink to this heading

{{ "**a** &amp; [b](c)" | strip_markdown }}

a & b: the Markdown rendered, then its tags removed and entities decoded, trimmed.

excerptLink to this heading

{{ content | excerpt }}

The Markdown before <!-- more --> rendered to HTML, or without the marker, the first <p> of the rendered HTML (an empty string when there is none).

where_expLink to this heading

{{ collections.all | where_exp: "item", "item.data.draft != true" }}

The items for which the condition is true. The first argument names the item in the expression, the second is a Liquid condition. Both are required: where_exp needs a variable name and an expression: where_exp: "item", "item.data.draft != true".

group_by_expLink to this heading

{% assign years = collections.post | group_by_exp: "item", "item.data.date | date: '%Y'" %}
{% for year in years %}<h2>{{ year.name }}</h2>{{ year.size }} posts{% endfor %}

One { name, items, size } per value of the expression, in the order the values first appear. The expression can use filters.

sort_byLink to this heading

{{ collections.post | sort_by: "data.title" }}
{{ collections.post | sort_by: "data.date", "desc" }}

The items sorted by the value at a dotted path. Numbers and dates compare by value, other values as strings (ordinal). Items without the value are last in both orders. The sort is stable. The second argument is desc or descending for a descending sort. Without a path: sort_by needs the path of the value to sort by.

index_byLink to this heading

{% assign by_url = collections.all | index_by: "data.url" %}
{{ by_url["/docs/last/index.html"].data.title }}

An object of the items by the value at a dotted path. The first item of a value wins, and items without one are left out. Without a path: index_by needs the path of the key.

jsonLink to this heading

<script type="application/json">{{ sidebar | json }}</script>

The value as JSON. jsonify is the same filter. Site data, collections and other data objects are written in their own key order; other values go through Fluid's json filter. The result is not encoded again, in any output.

where, find_index, sliceLink to this heading

{{ api | where: "module", page.module }}
{{ api | find_index: "file", name }}
{{ api | slice: 10, 20 }}

Fluid's filters. When the input is a large data array of objects (or a slice of one) and the value a string, where and find_index use an index built once per array instead of scanning it, and a slice of a data array keeps using that index. The answers are Fluid's either way, including a nil item, which makes the filter return nil once it reaches it.

xml_escapeLink to this heading

{{ title | xml_escape }}

&, <, >, " and ' as &amp;, &lt;, &gt;, &quot; and &#39;. The result is not encoded again. In an XML file the output is XML-encoded already, so the filter is only needed in a step with encode: none (see output encoding).

absolute_urlLink to this heading

{{ page.url | absolute_url }}

site.url without its trailing slash, followed by the url with a leading slash: /x/ is https://example.com/blog/x/ for site.url: https://example.com/blog. A url with a scheme, // or mailto: is returned as it is. Without site.url, the url with a leading slash.

relative_urlLink to this heading

{{ "x/" | relative_url }}

The path of site.url followed by the url with a leading slash: /blog/x/ for https://example.com/blog. Absolute urls are returned as they are.

strip_htmlLink to this heading

{{ content | strip_html | truncate: 160 }}

The text without tags, comments, and script and style elements with their content. Entities stay as they are.

date_to_xmlschemaLink to this heading

{{ page.date | date_to_xmlschema }}

2020-01-02T03:04:05+00:00. A value that is not a date is returned as it is.

date_to_rfc822Link to this heading

{{ page.date | date_to_rfc822 }}

Thu, 02 Jan 2020 03:04:05 +0000, for RSS. A value that is not a date is returned as it is.

tocLink to this heading

{{ toc | toc: class: "toc", max-depth: 3 }}

The tree that the headings step sets as toc, as nested lists:

<ul class="toc"><li><a href="#setup">Setup</a><ul><li><a href="#install">Install</a></li></ul></li></ul>
Argument Default Meaning
class none The class of the outer <ul>.
max-depth 6 Entries deeper than this heading level are left out, with their children.

An empty tree, or a value that is not a list, is an empty string.

tLink to this heading

{{ "search.label" | t }}
{{ "pages.count" | t: count: 3 }}

The UI string at that key in <strings>.<locale> (i18n.ja, from _data/i18n/ja.yml), where strings is site.locales.strings and locale the page's locale. Else the default locale's string, else the key itself with a warning (no translation for 'missing.key' in 'i18n.en'). A key is a member ("search.label" as one key) or a dotted path of nested members. Named arguments replace placeholders: count: 3 replaces {count}. See Internationalization.

locale_urlLink to this heading

{{ page.url | locale_url: "ja" }}
{{ page.url | locale_url }}

The url in another locale, whether or not a page exists there: /docs/install/index.html is /ja/docs/install/ in ja. The url is normalized (no index.html), its locale prefix removed, then the prefix of the locale added (none for the default locale). Without an argument, the url without its prefix. An unknown locale is an error: locale_url: unknown locale 'xx'.

locale_ofLink to this heading

{{ page.url | locale_of }}

The key of the locale whose prefix starts the url (/ja/x/ is ja), the default locale's otherwise.

locale_pagesLink to this heading

{% assign pages = collections.all | locale_pages %}
{% for p in pages %}
<url><loc>{{ p.url | absolute_url }}</loc></url>
{% endfor %}

Every page the site serves in every locale, as { locale, lang, url, fallback, data } with the url normalized: each collection item with its locale, and with site.locales.fallback, for a page of the default locale under the locale root, one entry per locale that has no page at that url (fallback: true, with the default locale page's data). In the order of the items, each followed by its fallbacks. For sitemaps.

previous_item and next_itemLink to this heading

{% assign previous_post = collections.posts | previous_item %}
{% assign next_post = collections.posts | next_item %}
{% if previous_post %}<a href="{{ previous_post.data.url }}">{{ previous_post.data.title }}</a>{% endif %}

The item before or after the page in a collection, found by data.url (urls compared without index.html). The argument is the url to look for, the page's url by default. Nil at the ends of the collection and for a url that is not in it. A collection is indexed once by url, so a layout that uses them on every post stays linear, unlike a loop over the collection. The page depends on its own item and on the neighbor, not on the whole collection: editing another post does not render it again.

{% assign nav = sidebar | nav_active: page.url %}

A sidebar is a list of items: a url, or an object with label (a string, or labels by locale), link, items (a group), and anything a layout reads (icon, badge, collapsed, external). nav_active returns the sidebar with active: true on the url's item and open: true on its ancestors. Bare urls become { label, link }, labeled with the title of their page in collections.urls.

Every navigation filter compares links and urls without index.html, and removes the url's locale prefix when no link of the sidebar has one. A page that uses one depends on the whole sidebar. See Navigation and sidebars.

{% assign pn = sidebar | nav_prev_next: page.url %}
{% if pn.prev %}<a href="{{ pn.prev.link }}">{{ pn.prev | nav_label }}</a>{% endif %}

{ prev, next }: the leaves next to the url's item in the same group (none across groups, none at the ends). Nil when the url is not in the sidebar.

{% assign trail = sidebar | nav_breadcrumbs: page.url %}
{% for item in trail %}{{ item | nav_label }} / {% endfor %}

The items from the top of the sidebar to the url's item. Empty when the url is not in the sidebar.

{{ sidebar | nav_flatten | map: "link" | join: "," }}

The leaves of the sidebar in order: the items with a link and no items.

{% assign section = sidebar | nav_section: page.url %}

The top-level item that contains the url's item, or nil.

{{ item | nav_label }}
{{ item | nav_label: "ja" }}

The label of an item in a locale (default: the page's locale): a string label, or the locale's member of an object of labels, else the default locale's, else its first one. A bare url is its own label.

image_urlLink to this heading

<meta property="og:image" content="{{ 'images/hero.png' | image_url: width: 1200, format: 'jpeg' | absolute_url }}">

Makes one variant of a source image, adds it to the outputs of the page, and returns its url (/assets/images/hero-1200.<hash>.jpeg). Arguments: width, format, quality, output. Without width or format, the first of the markdown.images defaults, else the source's own. An SVG or a GIF is copied as it is. The source is relative to the page's folder, or to the content folder when it starts with /. See Images.

image_sizeLink to this heading

{% assign size = "images/a.svg" | image_size %}{{ size.width }}x{{ size.height }}

{ width, height } of a source image, as displayed. Nothing is written; the source is a dependency of the page. A file that is not an image is an error: '<src>' is not an image format douze reads (png, jpeg, webp, avif, gif, svg).

social_image_urlLink to this heading

<meta property="og:image" content="{{ page | social_image_url: 'og{{ url }}.png' | absolute_url }}">

The url of the page's social image: the output template of its social-image step, passed as the argument and rendered with the page's data. The input is not read. Without an argument: social_image_url needs the output template of the social-image step.

TagsLink to this heading

Tag Result
image The variants of an image and their <picture> or <img> markup.
markdown Its body rendered as Markdown.
include_markdown A Markdown file of the content folder, rendered with the page's variables.
slot A named part of a shortcode body.
error Fails the page with a message.
warn Logs a warning.
Shortcodes A tag per file of the shortcodes folder.

imageLink to this heading

{% image "images/dashboard.png", alt: "The dashboard", widths: [640, 1280], formats: ["webp", "png"], sizes: "(min-width: 60em) 50vw, 100vw", class: "figure" %}
{% image "/images/arch.svg", alt: "Architecture" %}
{% image light: "images/a-light.png", dark: "images/a-dark.png", alt: "The flow" %}

Makes the variants of a source image, adds them to the outputs of the page, and writes their markup. Arguments are comma separated, positional or name: value; values are strings, numbers, true, false, nil, lists ([640, 1280]) and variables (page.hero).

Argument Default Meaning
source (positional) The image, relative to the page's folder, or to the content folder with a leading /.
light, dark Two sources: one <picture> whose dark sources have media="(prefers-color-scheme: dark)".
theme media attribute writes two elements with data-theme="light" and data-theme="dark" instead.
alt none The alt attribute.
widths markdown.images.widths, else the source's width Variant widths; never wider than the source.
formats markdown.images.formats, else the source's format webp, avif, png, jpeg.
quality markdown.images.quality, else 80 The quality of lossy formats.
output markdown.images.output, else /assets/images/ The folder of the variants.
sizes none The sizes attribute.
class none The class attribute.
loading markdown.images.loading, else lazy The loading attribute.
decoding async The decoding attribute.
any other name An attribute of the <img>: true without a value, false and nil left out.

Variants are written as <name>-<width>.<hash>.<ext>; an SVG or a GIF is copied as <name>.<hash>.<ext> with its size read from the file. The markup is a <picture> with a <source> per format but the last, and an <img> of the last format at its largest width with width and height; one format gives a plain <img>:

<img src="/assets/images/a.eafe29e7.svg" width="40" height="20" alt="A" loading="lazy" decoding="async">

Errors: the image tag needs a source: {% image "path" %} or {% image light: "path", dark: "path" %}, the image tag takes one source; name the other arguments, the image tag takes a source or 'light', not both, image theme must be 'media' or 'attribute', not '<value>'. Images other than SVG and GIF need libvips. See Images.

markdownLink to this heading

{% markdown %}
Some *Markdown* in a layout.
{% endmarkdown %}

Renders its body as Markdown to HTML with the site's pipeline, in layouts and HTML pages. In a Markdown page its output is a raw region that the page's Markdown pass keeps as it is.

include_markdownLink to this heading

{% include_markdown "reference/options.md", version: "2.0" %}
{% include_markdown "./shared/note.md" %}

Renders a Markdown file as a Liquid template with the page's variables. The path is relative to the content folder, or with ./ and ../ to the including file. The file's front matter values are variables that the page's names hide, and the named arguments hide both. In a Markdown page, the output is Markdown source that the page renders, every line indented like the tag so that it stays in its list item; elsewhere it is rendered to HTML. Its fences are not Liquid. Includes nest up to 16 deep, and the page renders again when the file changes. A partial that is not a page sets permalink: false.

Errors: include_markdown: '<path>' not found in '<folder>', include_markdown: '<path>' is outside the source folder, include_markdown: more than 16 nested includes: ..., and include_markdown takes a path and named arguments: {% include_markdown "path.md", name: value %}.

slotLink to this heading

{% card %}
{% slot "title" %}Get started{% endslot %}
Body text.
{% endcard %}

In a shortcode body, renders <div data-slot="title">...</div>, its content rendered like a body (to HTML in a Markdown page), so that the shortcode template can place the parts of its body. It takes one positional name: slot takes a name: {% slot "name" %}.

error and warnLink to this heading

{% if api == nil %}{% error "unknown API reference " | append: name %}{% endif %}
{% warn "this page uses a deprecated layout" %}

error fails the page with the position of the tag: error: render: /docs/a.md(12,3): unknown API reference Foo. warn logs a warning with the position: warning: render: /index.html(27,1): careful. The message is any Liquid expression, with filters.

ShortcodesLink to this heading

A shortcode is a .liquid or .html file directly in the shortcodes folder (site.shortcodes, default shortcodes in the includes folder). Every template can use it as a tag named after the file: shortcodes/link_card.liquid is {% link_card %}.

---
block: true
display: block
args: [label]
params: [variant]
---
<div class="tabs" data-label="{{ label }}" data-variant="{{ variant }}">{{ body }}</div>
Front matter Default Meaning
block false true: a paired tag, {% tabs %}...{% endtabs %}.
display block when paired, inline otherwise block: in a Markdown page, the output is a raw region at the column of the tag. inline: the output is written in the text, and a paired body has no <p>.
args none Names of the positional arguments, which become variables.
params none Names of the named arguments the template reads: one a call does not pass is nil instead of the page's value of that name.

A call takes positional values and name: value pairs separated by commas, and any value or variable ({% tab page.title %}). The template sees:

Name Value
args The positional arguments, as a list.
each args name The positional argument at that position.
each named argument Its value.
body Paired tags: the body rendered with the page's variables, then in a Markdown page as Markdown to HTML.
source Paired tags: the body before Markdown.
anything else The page's names, as in an include: page, title, data, collections, site.

A shortcode can use another one. A page renders again when a shortcode it uses changes. Shortcode templates are not strict, so their optional arguments work with strict: true.

Names are lowercase letters, digits and underscores, starting with a letter or _. Invalid shortcode files stop the build before it starts (exit code 2), with their position:

Message
'<file>' is not a shortcode name: use lowercase letters, digits and underscores
shortcode '<name>' hides a built-in tag; rename the file
shortcode '<name>' is defined twice
invalid front matter: <reason>
'block' of shortcode '<name>' must be true or false
'display' of shortcode '<name>' must be 'block' or 'inline'
'args' of shortcode '<name>' must be a list of names (lowercase letters, digits and underscores) (also params)
unknown key '<key>' in the front matter of shortcode '<name>'; expected 'block', 'display', 'args' or 'params'

An error while rendering names the shortcode and the page: error: render: /docs/a.md: shortcode 'tabs' (/_includes/shortcodes/tabs.liquid(3,12)): ..., and an unknown tag suggests a shortcode: Unknown tag 'tabss'; did you mean 'tabs'?. See Includes and shortcodes.

Esc to close