Template Data

Overview

Template data is content in key-value pairs used to hydrate a layout template. Template data is generally managed as content files in Markdown, YAML, or JSON format.

Example

This example shows an approximation of a template data object.

 1{
 2    created_at: "2025-01-27T17:00:00-08:00",
 3    updated_at: "2025-01-27T17:00:00-08:00",
 4    title: "Template Data",
 5    description: "HyperTemplates generates template data from content files",
 6    author: {
 7        name: "Jane Doe",
 8        href: "https://janedoe.com",
 9    },
10    content: "## Overview\n\nLorem ipsum, hipsters get some."
11}

Template attributes reference template data using "dot notation" property accessors. The name of the property being accessed is the template data key, and the value of the property being accessed is the template data value.

In this sample, title and author.name are valid template data keys (property names), and their corresponding template data values (property values) are Template Data and Jane Doe.

Example template data source files

The example template data provided above could be managed via any one of the following source files in Markdown, YAML, or JSON format. The following example content files will generate identical template data.

index.md

 1---
 2created_at: 2025-01-27T17:00:00-08:00
 3updated_at: 2025-01-27T17:00:00-08:00
 4title: Template Data
 5description: HyperTemplates generates template data from content files
 6author:
 7    name: Jane Doe
 8    href: https://janedoe.com
 9---
10
11## Overview
12-----------
13
14Lorem ipsum, hipsters get some.

index.yaml

 1created_at: "2025-01-27T17:00:00-08:00"
 2updated_at: "2025-01-27T17:00:00-08:00"
 3title: Template Data
 4description: HyperTemplates generates template data from content files
 5author:
 6    name: Jane Doe
 7    href: https://janedoe.com
 8content: |
 9    ## Overview
10
11    Lorem ipsum, hipsters get some.

index.json

 1{
 2    "created_at": "2025-01-27T17:00:00-08:00",
 3    "updated_at": "2025-01-27T17:00:00-08:00",
 4    "title": "Template Data",
 5    "description": "HyperTemplates generates template data from content files",
 6    "author": {
 7        "name": "Jane Doe",
 8        "href": "https://janedoe.com"
 9    },
10    "content": "## Overview\n\nLorem ipsum, hipsters get some."
11}

Specification

Template data object

The HyperTemplates rendering system always expects key-value data as an input to hydrate a layout with. This key-value data input is referred to as the "template data object". Template data objects do not have required fields. The only structural requirement for template data is that template data keys must be strings.

 1{
 2    site: {
 3        title: "ACME Inc.",
 4        favicon: "favicon.png",
 5    },
 6    page: {
 7        created_at: "2025-01-27T17:00:00-08:00",
 8        layout: "default.html",
 9        title: "Hello, world",
10        content: "Lorem ipsum, hipsters get some.",
11    },
12}

This is an approximation of a template data object.

NOTE: Applications may combine template data from multiple sources into a single template data object before processing. For example, the hyperctl build command combines data from a website configuration file with individual page content into a single template data object. The resulting template data object maps the website configuration template data to the site key, and page template data to the page key, similar to the sample shown above.

To learn more, please visit the HyperTemplates content management system and/or hyperctl reference documentation.

Template data properties

HyperTemplates template data objects contain key-value pairs known as "properties". A template data property has a key and a value.

 1{
 2    site: {
 3        title: "ACME Inc.",
 4        favicon: "favicon.png",
 5    },
 6    page: {
 7        created_at: "2025-01-27T17:00:00-08:00",
 8        layout: "default.html",
 9        title: "Hello, world",
10        content: "Lorem ipsum, hipsters get some.",
11    },
12}

In this example, line 9 contains a template data property with the key page.title and the value Hello, world.

Template data keys

Template data keys are "dot notation" property accessors to properties in a template data object. The name of the property being accessed is the template data key.

 1{
 2    site: {
 3        title: "ACME Inc.",
 4        favicon: {
 5            href: "favicon.png",
 6            sizes: "128x128",
 7        },
 8    },
 9    page: {
10        created_at: "2025-01-27T17:00:00-08:00",
11        layout: "default.html",
12        title: "Hello, world",
13        content: "Lorem ipsum, hipsters get some.",
14    },
15}

In this example, there are 8 template data keys: site, site.title, site.favicon, site.favicon.href, site.favicon.sizes, page, page.created_at, page.layout, page.title, and page.content.

NOTE: template data objects are not vanilla Javascript objects, so template data keys may reference properties that do not exist (what would be considered "undefined" objects in Javascript parlance) without penalty. For example, in the sample above, the template data key site.foo.bar would simply result in a null value rather than an error due to site.foo being "undefined".

Template data values

Template data values are values of properties being accessed in a template data object.

 1{
 2    site: {
 3        title: "ACME Inc.",
 4        favicon: "favicon.png",
 5    },
 6    page: {
 7        created_at: "2025-01-27T17:00:00-08:00",
 8        layout: "default.html",
 9        title: "Hello, world",
10        content: "Lorem ipsum, hipsters get some.",
11    },
12}

In this example, the template data value for the key page.title is Hello, world.

Template data sources

At a high level, the HyperTemplates core specification is primarily concerned with HTML templates (layouts) and template data (content) as inputs, which are used to generate individual web pages (HTML documents) as outputs. However, the HyperTemplates core templating engine doesn't actually have any built-in concept of data sources (i.e. where the template data comes from). The closest thing to a completely unopinionated implementation of the HyperTemplates core templating engine is the hyperctl render command, which accepts a single data file as an input.

In most implementations multiple data sources are combined into a single template data object. The HyperTemplates CMS is one such implementation, which incorporates several data sources:

ht (builtins): ht.* prefixed template data properties provided by HyperTemplates, including ht.version, ht.release_date, and template iterator properties (see ht-template template data).
build: build.* prefixed template data properties generated by the hyperctl build command, including build.id (see builds).
env: env.* prefixed template data properties sourced from HT_ environment variables (see environment data).
site: site.* prefixed template data properties sourced from site.yaml or site.json (including custom website properties)
global: data.* prefixed template data properties sourced from data files in site.data_dir (supports YAML, JSON, and OPML formats; see namespaces)
theme: theme.* prefixed template data properties sourced from data files in theme.data_dir (supports YAML, JSON, and OPML formats; see namespaces)
layout: layout.* prefixed template data sourced from <meta> elements with layout: prefixed name attributes (see layout data)
page: page.* prefixed template data sourced from page data files (supports Markdown, YAML, and JSON formats; includes custom page properties)

The site, page, and namespace data sources are technically outside of the scope of the core specification (i.e. this document), but we are enumerating them here for reference.

NOTE: The HyperTemplates CLI (hyperctl) and libraries (coming soon) have built-in support for parsing template data from files in Markdown, YAML, and JSON formats. These files may still be considered valid template data if they are "empty", however completely empty JSON files (containing zero bytes) may cause JSON parsing errors in some implementations, so a JSON format template data source would be considered empty (and still valid) as long as they contain opening and closing curly braces (i.e. {}).

Environment data

Template data properties can be provided at build time using the HT_ prefix. Environment template data can be nested using underscores.

1export HT_lang="en"
2export HT_version="v1"
3export HT_example_foo="bar"
4export HT_example_bar="baz"

 1{
 2    env: {
 3        lang: "en",
 4        version: "v1",
 5        example: {
 6            foo: "bar",
 7            bar: "baz",
 8        },
 9    },
10}

Layout data

Additional layout-scoped data can be added to any layout or other layout fragment as <meta> elements with layout: prefixed name attributes.

NOTE: layout data <meta> elements are queried with an [attr^=value] prefix selector, equivalent to:
1document.querySelectorAll("meta[name^='layout:']")

Example:

1<meta name='layout:name' content='default'>
2<meta name='layout:copyright' content='Herd Works Inc'>
3<meta name='layout:copyyear' content='2024'>

In this example three layout data properties are defined:

A layout.name property, with the value of default (line 1)
A layout.copyright property, with the value of Herd Works Inc (line 2)
A layout.copyyear property, with the value of 2024 (line 3)