Template Variables

Overview

Template variables are placeholders that are replaced by template data. Template variables can be used to populate HTML element attributes, and HTML element contents.

Example

This example shows how variable substitution works in HyperTemplates.

1<head>
2    <title ht-apply>${ site.title } | ${ page.title }</title>
3    <meta ht-apply name='description' content='${ page.description }'>
4    <!-- ...other <head> elements... -->
5</head>

If site.title is HyperTemplates, page.title is Template Variables, and page.description is Learn more about the HyperTemplates variable substitution system., the rendered HTML for this fragment would be as follows:

1<head>
2    <title>HyperTemplates | Template Variables</title>
3    <meta name='description' content='Learn more about the HyperTemplates variable substitution system.'>
4    <!-- other <head> elements -->
5</head>

Specification

Supported elements

Template variables can be used with any HTML element.

See template variable syntax for more information on the template variable CSS syntax, which is required when applying variables to a <style> element or style attribute.

Template variable syntax

Template variables are defined using delimiters. The default syntax for a template variable is a string that begins with ${ and ends with }.

Example

1<a href='${ page.path }' ht-apply>${ page.title }</a>

An alternate syntax is required for <style> elements and style attributes where the default variable syntax is invalid CSS. Template variables in a <style> elements or style attributes begin with --ht-value( and end with ). The --ht-value() syntax also supports CSS-style fallback values as an optional second argument. Fallback values can be any valid CSS value.

Example

1<head>
2    <!-- other <head> elements -->
3
4    <style id='layout'>
5        :root {
6            --color-1: --ht-value("site.colors.default", rgba(236, 120, 184, 1.0))
7        }
8    </style>
9</head>

In this example the --ht-value( ... ) variable will be replaced with the template data property site.colors.default if it is defined, or else it will use a fallback value of rgba(236, 120, 184, 1.0).

Template variables are not Javascript (or CSS)

The default template variable syntax is inspired by Javascript template literals, but they are not Javascript. However, the syntax for performing "string interpolation" with HyperTemplates variables should look & feel very similar to a Javascript template literal that is only doing variable substitution.

Here's an example of how to perform string interpolation using a Javascript template literal:
1`${ site.title } | ${ page.title }`
Note the Javascript-required ` backtick characters.

This same string interpolation is possible using HyperTemplates variables, sans backticks:
1<title ht-apply>${ site.title } | ${ page.title }</title>
Similarly, the template variable CSS --ht-value() syntax is inspired by CSS custom functions, but they are not CSS. By adopting the custom function syntax, template variables in <style> elements are valid CSS. If/when a CSS template variable cannot be processed by HyperTemplates (e.g. due to missing template data), they will be present in the generated HTML files and all major browsers will simply ignore them.

Template variable functions

Template variables support functions, and there are three built-in functions: get, text, and markdown.

get function

The get function gets template data values.

The get function supports two arguments: a comma-separated list of [template data keys], and a default value. Default values must be quoted, and they must be the last argument passed to the get function.

Examples

1<title>${ get "page.title, site.title", "Default Title" }</title>

1<title>${ get page.title, site.title, "Default Title" }</title>

Both examples shows the get function with two arguments:

A comma-separated list of [template data keys] (i.e. page.title, site.title)
A string literal default value (i.e. "Default Title")

The HyperTemplates variable parser automatically recognizes ${ get page.title, site.title, "Default Title" } as two arguments and not three because it detects the argument types – the unquoted template data keys vs the quoted default value – in addition to the delimiters (the comma characters).

text function

The text function escapes HTML.

Example

If a template data property contains HTML markup that should not be rendered as HTML elements, you will need to use the text function to escape the HTML.

For example, if you have a page with the following front matter:

content/index.md

1---
2created_at: 2026-05-11T11:00:00-07:00
3title: Hyper<Templates>
4---

When the resulting ${ page.title } template variable is parsed as HTML it may yield unexpected results:

1<!-- fragment -->
2<h1 ht-apply>
3    ${ page.title }
4</h1>
5
6<!-- output -->
7<h1>
8    Hyper<Templates> <!-- browsers will display "Hyper" and ignore the <Templates> tag element -->
9</h1>

Use the text function to escape HTML strings:

1<!-- fragment -->
2<h1 ht-apply>
3    ${ text page.title }
4</h1>
5
6<!-- output -->
7<h1 ht-apply>
8    Hyper&lt;Templates&gt; <!-- browsers will display "Hyper<Templates>" -->
9</h1>

markdown function

The markdown function converts Markdown strings to HTML elements.

Example

If a template data property contains Markdown strings, you may see the markup as plain text.

 1<!-- fragment -->
 2<div ht-apply>
 3    ${ page.overview }
 4</div>
 5
 6<!-- output -->
 7<div>
 8    ## Hello world
 9      
10    Lorem ipsum, hipsters get some.
11</div>

Use the markdown function to convert Markdown strings to elements:

 1<!-- fragment -->
 2<div ht-apply>
 3    ${ markdown page.overview }
 4</div>
 5
 6<!-- output -->
 7<div>
 8    <h2>Hello world</h2>
 9    <p>Lorem ipsum, hipsters get some.</p>
10</div>

NOTE: the markdown function is available in HTML content template variables, but it is not allowed in HTML attribute variables.

Plugin functions

Additional functions are added using template variable plugins.

Template variable plugins

HyperTemplates supports custom template variable functions via plugins. A template variable plugin is created by adding a Javascript file that exports a default function to the site.config.plugins_dir or theme.config.plugins_dir directory.

Examples

The following example creates a plugin called uppercase (created via the plugins/uppercase.js file).

plugins/uppercase.js

1// uppercase transforms strings to uppercase
2export default function uppercase(input="") {
3    return input.toUpperCase()
4};

PROTIP: in case you're wondering why we chose uppercase as an example here when text-transform: uppercase; already exists, it's because this contrived uppercase example well illustrates two important truths about HyperTemplates plugins: they are incredibly simple to create, and in many cases completely unnecessary!

Implicit gets

A template variable that doesn't begin with a registered function name (including plugins) is treated as an "implicit get".

1<!-- this is an impliciet get -->
2<h1>${ page.title, "Default Title" }</h1>
3
4<!-- this is a explicit get -->
5<h2>${ get page.title, "Default Title" }</h2>

Example:

1<a href='${ link.href }' ht-apply>${ link.label, link.title, "Placeholder" }</a>