Template values, tags and filters
Values a page can print
Section titled “Values a page can print”| Name | What it holds |
|---|---|
site.name |
The display name, such as “Saltmere Marina”. |
site.address |
The address visitors use: the site’s own domain, or its sitepeek.page address before it has one, with no / at the end, such as https://saltmeremarina.ca. {{ site.address }}{{ post.url }} is a full address, as a feed needs. A preview has it too, before the first publish. |
page.title, page.path, page.lang |
The current page’s title, address and language, plus its other settings. |
page.translations |
The same page in the site’s other languages, each with lang, path and name, the language’s name in that language, such as “Français”. |
data.NAME |
The data in _data/NAME.yml or .json, or the list of files in the folder _data/NAME/, in file name order. Each file there can be Markdown, YAML or JSON; a Markdown file’s text is its body. On a page in another language, the translated fields come from the copy in _data/fr/ (for French). |
item |
On an each: page, the record this page is for. |
url on a record |
For each record an each: page is made from, the address of its page in the current page’s language. In a loop such as {% for post in data.news %}, it is post.url. |
content |
In a layout, the page it wraps. |
live.item, live.items, live.credit |
Inside {% live %}: one record, such as the current weather, and a list of records, such as the forecast, from a source of live data, and the credit line the source requires. |
Tags: assign, break, capture, case, comment, continue, cycle, echo, for, if, liquid, raw, unless, plus render for files in _includes, live, and text for writing in each language (see Languages). A name that is not one of the values listed above, such as a typo in site.titel, or an unknown filter stops the build with the file, the line and a fix. A field marked optional in a data folder’s schema, and missing from one record, is empty, so in a loop such as {% for post in data.news %}, {% if post.photo %} works on posts without a photo.
Filters: the standard filters of LiquidJS, the Liquid used here, such as append, default, downcase, join, size, sort, split, truncate and where, except raw. Also json, described under Text and HTML, date, which uses the site’s time zone and the page’s language, markdown, described above, t, which prints a string in the page’s language, and lang_path, which turns a page’s main address into its address in the page’s language: '/about' | lang_path is /fr/a-propos on a French page.
Text and HTML
Section titled “Text and HTML”{{ }}prints text, everywhere, including inside a{% live %}block. Less-than and greater-than signs, ampersands and quotes are turned into their HTML codes, so data, front matter, form text, translations and live data can never add HTML or a script to a page.- Six things are printed as they are, not turned into HTML codes:
contentin a layout, the result of{% render %}, the result of themarkdownfilter, a{% live %}block, a{% text %}block, and the result of thejsonfilter inside ascripttag of typeapplication/json. Anywhere else,jsonoutput is turned into HTML codes like any other value. Themarkdownfilter and the{% text %}block remove scripts,styletags,on...attributes such asonclick, and links that do not start withhttps:,http:,mailto:,tel:,/or#. - There is no way to print raw HTML from data. Write HTML in a page or include, or Markdown in a data file. A
captureholds text, so HTML put in acaptureprints as text; use an include instead. - Links from data are checked. A value printed inside
href,srcoractionmust start with one of the prefixes above, or the build stops and names the file. {{ }}is refused inside code, with one exception below. HTML codes do not make a value safe inside JavaScript or CSS: inside a JavaScript template string, the text between backticks, a value such as${1+1}keeps its characters after HTML encoding and runs as code. So the build stops, naming the file and line, if{{ }}appears inside ascripttag, anon...attribute such asonclick, astyletag or astyleattribute. The exception is ascripttag of typeapplication/jsonthat holds nothing but one value printed with thejsonfilter, as shown next.- To give data to a script, put it in a JSON block with the
jsonfilter. It writes the value as JSON, with less-than and greater-than signs and ampersands turned into codes a browser cannot read as HTML. The script then reads it withJSON.parse:
<script type="application/json" id="prices">{{ data.prices | json }}</script><script> const prices = JSON.parse(document.getElementById("prices").textContent);</script>A single value can also go in a data- attribute, such as data-price="{{ item.price }}", which the script reads as text from element.dataset.price.
- To style from data, choose between classes written in the style sheet, such as
class="tag-{{ item.kind }}", where the value must be lowercase letters, numbers and hyphens. - Liquid reads only this site’s files.
renderreads only from_includes,layoutonly from_layouts, andtonly fromlocales.{% live %}reads only sources connected to this site.
What a page may load
Section titled “What a page may load”Each page’s Content Security Policy is a rule the browser follows about where the page may load things from. It sets these rules:
- Scripts may load from the site itself, from
/_ws/, and from anyhttpsaddress. Inline scripts, module scripts and import maps are allowed.ws pushlists every outside domain a page loads scripts or style sheets from, such asScripts and style sheets from other domains: cdn.jsdelivr.net, so a builder sees them. It never blocks them. Owners never add scripts: their edits in the owner’s tools are text, and analytics comes only from the platform. - Style sheets may load from the site itself, from
/_ws/, and from anyhttpsaddress, such as Google Fonts or a library’s own CSS.ws pushlists their domains with the script domains. Inline styles are allowed. - Images, fonts, video,
fetchcalls and frames such as a YouTube video or Google map may come from anyhttpsaddress. - A page must not stop itself from being shown in a frame. The screens where an owner points at part of their site, on
app.websitestrategy.com, show it in a frame.