ht-attrs attribute

`ht-attrs` attribute reference

Overview

The ht-attr and ht-attrs attributes annotate target HTML elements with one or more HTML attributes.

Example

This example shows the ht-attrs attribute being used to template the page description <meta> element.

layout.html

 1<html>
 2    <head>
 3        <meta charset='utf-8'>
 4        <title>Acme Inc.</title>
 5        <meta name='description' content='Home of Acme Inc.' ht-attrs='content:site.description'>
 6    </head>
 7    <body>
 8        <article>
 9            <p>Lorem ipsum, hipsters get some.</p>
10        </article>
11    </body>
12</html>

This template will cause the page description <meta> element content attribute to be populated with the value of the template data page.description or site.description property, or else do nothing (resulting in the default value "Home of Acme Inc." being used).

Specification

Supported elements

The ht-attr and ht-attrs attributes can be used with any HTML element.

1<a ht-attr='href:page.byline.href,site.byline.href' ht-content='page.byline.name,site.byline.name'></a>

Attribute syntax

The ht-attr and ht-attrs attributes define target HTML element attributes, expressed as a semicolon-separated list of name:value pairs. The value is a comma-separated list of dot-notation style references to one or more template data properties.

1ht-attrs='href:link.href,link.url;target:link.target'

In the following example, the <meta> element ht-attrs attribute configures a single named attribute: content. The <link> element ht-attrs attribute configures three named attributes: rel, href, and type.

1<meta name='description' ht-attrs='content:site.description'>
2<link rel='icon' ht-attrs='rel:site.favicon.rel;href:site.favicon.href;type:site.favicon.type'>

NOTE: in this example, if the template data site.favicon.rel property is not defined, the <link> element will use the default value of "icon" (as configured by the rel='icon' attribute).

Attribute variants

HyperTemplates attribute templating directives are available in two variants: ht-attr and ht-attrs. The attribute syntax is the same for both directives. The only difference between ht-attr and ht-attrs is that multiple ht-attr attributes are supported per HTML element.

NEW: the ht-attr attribute is new as of hyperctl 0.18.0. The only functional difference between the original plural ht-attrs attribute and the new singular ht-attr attribute is that HyperTemplates supports multiple ht-attr attributes per element, and only one ht-attrs attribute per element.

The following examples are functionally identical and they can be used interchangeably.
1
2<a ht-attr='href:link.href' ht-attr='rel:link.rel'>
1
2<a ht-attr='href:link.href;rel:link.rel'>
1
2<a ht-attrs='href:link.href;rel:link.rel'>
Determining which attribute templating style to use is effectively a matter of preference.

NOTE: if layouts or fragments are parsed using an HTML validator prior to rendering, some HTML validators may flag duplicate attributes as medium-low severity errors. However, HyperTemplates automatically removes ht-attr and ht-attrs attributes from generated HTML pages by default (see: site.config.tidy_mode)

Default values

The ht-attrs attribute will only cause attributes to be added to a target element if the specified template data property is found. In cases where no value is found, HyperTemplates ignores the attribute.

In scenarios where a default or fallback value is desired, simply set the element attribute in the template.

1<meta name='author' content='ACME Inc' ht-attrs='content:page.byline.name'>

In this example, if the template data page.byline.name property does not exist, HyperTemplates will do nothing. The end result will be a valid <meta> attribute with a value of "ACME Inc" (as configured by the content attribute).

Attribute names

The ht-attr and ht-attrs attribute can optionally specify the name of the attribute to be added to the target element. The ht-attr and ht-attrs attribute syntax is name:value. If no attribute name is specified, an ordinal value will be used (e.g. data-attr-0, data-attr-1, etc).

1<meta name='author' ht-attrs='content:page.byline.name,site.byline.name'>

In this example, HyperTemplates will set an element attribute named content to the value of the template data page.byline.name or site.byline.name property, or else do nothing.

Multiple attributes

The ht-attr and ht-attrs attribute can be used to configure multiple attributes on the target element. See attribute syntax for more information.

Attribute maps

The ht-attr and ht-attrs attributes support a shorthand for setting multiple attributes from template data objects. If an ht-attr or ht-attrs directive resolves to a template data object (a key:value pair), HyperTemplates will set one HTML attribute per template data key.

NOTE: attributes maps are syntactic sugar – an advanced templating feature for experienced template developers. They are great for simplifying template development, but they can add contextual complexity for template contributors – even if the contributor in question is the template author's future self. 😵‍💫

Example

To illustrate, consider the following example page:

content/blog/introducing-hypertemplates/page.md

 1---
 2created_at: 2025-06-12T08:00:00-07:00
 3layout: post
 4title: Introducing HyperTemplates
 5description: |
 6    The pure-HTML templating system for the modern web.
 7cover: cover-light.png
 8metadata:
 9  - name: "twitter:card"
10    content: "summary_large_image"
11  - name: "twitter:site"
12    content: "@herdworks"
13  - name: "twitter:title"
14    content: "Introducing, HyperTemplates"
15  - property: "og.type"
16    content: "article"
17  - property: "og.title"
18    content: "Introducing, HyperTemplaes"
19  - property: "og.description"
20    content: "The pure-HTML templating system for the modern web."
21  - property: "og.url"
22    content: "https://hypertemplates.net/blog/introducing-hypertemplates/"
23  - property: "og.image"
24    content: "https://hypertemplates.net/blog/introducing-hypertemplates/cover-light.png"

Before template data maps, a template fragment to render these Twitter Card and OpenGraph metadata properties might have looked like this:

1<!-- Iterate over page.metadata properties and create <meta> elements for each property -->
2<meta ht-template='metadata:page.metadata' ht-attrs='name:metadata.name; property:metadata.property; content:metadata.content' />

With template data maps, that same template fragment can be simplified to the following:

1<!-- Iterate over page.metadata properties and create <meta> elements for each property -->
2<meta ht-template='metadata:page.metadata' ht-attrs='metadata' />

The resulting output for both templates would be as follows:

1<!-- Iterate over page.metadata properties and create <meta> elements for each property -->
2<meta name='twitter:card' content='summary_large_image' />
3<meta name='twitter:site' content='@herdworks' />
4<meta name='twitter:title' content='Introducing, HyperTemplates' />
5<meta property='og.type' content='article' />
6<meta property='og.title' content='Introducing, HyperTemplaes' />
7<meta property='og.description' content='The pure-HTML templating system for the modern web.' />
8<meta property='og.url' content='https://hypertemplates.net/blog/introducing-hypertemplates/' />
9<meta property='og.image' content='https://hypertemplates.net/blog/introducing-hypertemplates/cover-light.png' />