ht-block directive

`ht-block` directive reference

Overview

The ht-block directive progressively enhances a custom element.

PROTIP: the ht-block directive is the only templating directive that is accessible from your content. ✨

The ht-block directive was heavily inspired by Hugo Shortcodes and is intended to be used for inserting custom elements into your content. This effectively exposes a subset of HyperTemplates templating capabilities to content management systems (i.e. whereever you edit content that will be rendered using HyperTemplates).

Specification

This example shows the ht-block directive being used to enhance a Markdown code block.

index.md

 1### Example
 2-----------
 3
 4This example shows the `ht-content` directive being used to template the `<title>` and `<h1>` elements.
 5
 6<code-snippet ht-block filename='layout.html' highlight='5,9' line-numbers='on'>
 7
 8```html
 9<!DOCTYPE html>
10<html>
11    <head>
12        <meta charset='utf-8'>
13        <title ht-content='page.title,site.title'>Placeholder Title</title>
14    </head>
15    <body>
16        <header>
17            <h1 ht-content='page.title'>Hello, world.</h1>
18        </header>
19        <article>
20            <p>Lorem ipsum, hipsters get some.</p>
21        </article>
22    </body>
23</html>
24```
25
26</code-snippet>

In fact, this example is an excerpt from the ht-content reference documentation content file.

Supported elements

The ht-block directive was designed to be used with custom elements.

Directive syntax

The ht-block directive is an HTML boolean attribute. If it is present, HyperTemplates will process the element as a nested layout template.

Example:

1<pull-quote ht-block='false'>
2
3Lorem ipsum, hipsters get some.
4
5</pull-quote>

This example demonstrates that ht-block directives are invoked by the presence of the ht-block attribute (i.e. ht-block attribute values are ignored).

Custom element include sources

HyperTemplates processes HTML elements with the ht-block directive as nested layout templates. In practice, ht-block elements are what you might expect if you combined ht-include and ht-template, with one important difference: unlike the ht-include directive, ht-block uses tag names to lookup the corresponding layout fragment.

Example

1<newsletter-signup ht-block></newsletter-signup>

In this example Markdown document, the ht-block directive will cause HyperTemplates to replace the newsletter-signup element with the elements/newsletter-signup.html fragment.

Custom element template data

HyperTemplates processes HTML elements with the ht-block directive as nested layout templates with access to page.* and block.* template data properties. In practice, ht-block elements are what you might expect if you combined ht-include and ht-template. ht-block differs from ht-template in how their respective template data objects are constructed. The ht-block directive will cause HyperTemplates to construct a template data object using the placeholder element attributes as template data properties, plus a property called block.content with the body of the element as its value.

Example

1<pull-quote ht-block cite='Caleb Hailey'>
2
3The HyperTemplates `ht-block` directive is fun and useful.
4
5</pull-quote>

In this example Markdown document, the ht-block directive will cause HyperTemplates to render the layout of elements/pull-quote.html with a template data object containing two properties: block.cite and block.content.

1{
2    block: {
3        cite: "Caleb Hailey",
4        content: "<p>The HyperTemplates <code>ht-block</code> directive is fun and useful.</p>"
5    }
6}

NOTE: beginning with hyperctl version 0.18.0, all ht-block element attributes are parsed as block.-prefixed template data properties (see template data sources).
Example

Let's take this page data file as an example:
 1---
 2created_at: "2026-04-21T12:00:00-07:00
 3title: Hello ht-block world
 4---
 5
 6Hello, world. 
 7
 8This is an example markdown document containing a @hypertemplates.net `ht-block` element.
 9
10<example-element ht-block foo='bar'></example-element>
11
12Please visit the [`ht-block` reference documentation] to learn more.
13
14
15[`ht-block` reference documentation]: https://hypertemplates.net/docs/reference/core/directives/ht-block/
In hyperctl versions 0.14.x through 0.17.x, the resulting template data would look as follows:
1{
2    foo: "bar" // accessible to ht-block fragments as "foo"
3}
In hyperctl versions 0.18.0 and newer, the resulting template data would look as follows:
1{
2    block: {
3        foo: "bar" // accessible to ht-block fragments as "block.foo"
4    }
5}
In hyperctl versions 0.19.0 and newer, the resulting template data would also include the page.* properties:
1{
2    page: { ... },
3    block: {
4        foo: "bar" // accessible to ht-block fragments as "block.foo"
5    }
6}

NEW: hyperctl version 0.19.0 adds support for page.* template data properties in ht-block elements.